-
Notifications
You must be signed in to change notification settings - Fork 7
/
Copy pathhercoper.html
924 lines (813 loc) · 31.5 KB
/
hercoper.html
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
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 3.0//EN" "html.dtd">
<HTML>
<head>
<title>Hercules Version 4: Installation and Operation</title>
<link rel="stylesheet" type="text/css" href="hercules2.css">
<link rel="shortcut icon" href="images/favicon.ico" />
<link rel="icon" href="images/favicon.ico" />
<style>
li.spaced:not(:last-child) {
margin-bottom: 5px;
}
</style>
</head>
<body>
<div id="header">
<table class="hdr">
<tr>
<td rowspan="2" class="hdrlogo">
<a href="index.html"><img src="images/hercpic-rblk-256.gif" alt="logo" class="hdrlogo" /></a>
</td>
<td class="hdr">
<h1 class="hdr">Hercules Version 4: Installation and Operation</h1>
</td>
</tr>
<tr>
<td class="hdr">
<h2 class="hdr">Operating Procedures</h2>
</td>
</tr>
</table>
<hr />
</div>
<div id="content">
<h3>Contents</h3>
<blockquote>
<p>
<a href="#operating">Operating Procedure</a>
<ul>
<li><a href="#arguments">Command line arguments</a>
<li><a href="#keyboard">Using the keyboard</a>
<li><a href="#commands">Panel commands</a>
<li><a href="#RCFILE">The .RC ("run commands") file</a>
<li><a href="#HAO">The Hercules Automatic Operator (HAO)</a>
</ul>
<p>
<a href="#support">Technical Support</a>
</p>
</blockquote>
<hr />
<h3 class="skiplogo" id="operating">Operating Procedure</h2>
<p class="warning">
<em>Note: If you intend to run any licensed software on your PC
using Hercules, it is your responsibility to ensure that you do not
violate the software vendor's licensing terms.</em>
<h4 class="skiplogo" id="arguments">Command line arguments</h4>
<p>
To start Hercules enter this command at the host's command prompt:
<blockquote><code><pre>
hercules [ -f <em>filename</em> ] | [ --config=<em>filename</em> ]
[ -r <em>rcfile</em> ] | [ --rcfile=<em>rcfile</em> ]
[ -b <em>logofile</em> ] | [ --herclogo=<em>logofile</em> ]
[ -d ] | [ --daemon ]
[ -e ] | [ --externalgui ]
[ -p <em>dyndir</em> ] | [ --modpath=<em>dyndir</em> ]
[ -l <em>modname</em> ] ... | [ --ldmod=<em>modname</em> ] ...
[ -s <em>symbol=value</em> ] ... | [ --defsym=<em>symbol=value</em> ] ...
[ -v ] | [ --verbose ]
[ -h ] | [ --help ]
[ -t[factor]] | [ --test[=factor]]
[ > <em>logfile</em> ]
</pre></code>
</blockquote>
<p>
where:
<blockquote>
<dl>
<dt><code><em>filename</em></code><p><dd>
is the name of the configuration file.
The default, if none is specified, is <b><em>hercules.cnf</em></b>.
The default may be overridden via the <code>HERCULES_CNF</code>
environment variable.
<p>
<dt><code><em>rcfile</em></code><p><dd>
is the name of the Hercules <a href="#RCFILE">.RC run commands file</a>.
The run commands file automatically executes panel commands upon startup.
<p>
<dt><code><em>logofile</em></code><p><dd>
is the name of the Hercules logo file. The logo file is the
initial welcome screen presented when a TN 3270 terminal connects
to a hercules 3270 device.
<p>
<dt><code><em>-d</em></em></code><p><dd>
specifies that Hercules is to be run in 'daemon' mode,
wherein it runs invisibly with no attached console.
<p>
<dt><code><em>-e</em></em></code><p><dd>
indicates Hercules is to be controlled by an External GUI.
<p>
<dt><code><em>dyndir</em></code><p><dd>
is the directory from which dynamic modules are to be loaded.
The default depends on the host platform on which Hercules
is being run. This option overrides the default.
<p>
<dt><code><em>modname</em></code><p><dd>
is the name of an additional dynamic module to be loaded
at startup. More than one additional module may be specified,
although each must be preceded with the <code>-l</code>
option specifier.
<p>
<dt><code><em>symbol=value</em></code><p><dd>
the name of a symbol and its associated value to be used in configuration
file processing or panel commands. See the command 'defsym'
for more information on using symbols. The '-s' option may be repeated.
Note: 'value' may be quoted to contain imbedded blanks.
<p>
<dt><code><em>-v</em></code><p><dd>
sets the message-level to verbose. This is the same as
entering the command <code>msglvl +verbose</code>.
<p>
<dt><code><em>-h</em></code><p><dd>
displays help information regarding the syntax of command-line arguments.
<p>
<dt><code><em>-t[factor]</em></code><p><dd>
starts Hercules in test mode, activating special .rc file script
commands used only by QA test scripts. Normal Hercules use should
never specify this switch.
<p>
<code>factor</code> is an optional test timeout factor within the
range 1.0 to 14.3. The test timeout factor is used to adjust each
test script's specified timeout value to compensate for the speed
of the system on which they are running.
<p>
Use a factor greater than 1.0 on slower systems to slightly increase
timeout values giving each test more time to complete.
<p>
Please note that due to manner in which command line arguments are
parsed this option must be specified as one argument. Thus "-t2.0"
is correct whereas "-t 2.0" is not. Oftentimes it is easier
to use the long <code>--test=<i>factor</i></code> syntax instead.
<p>
Test timeout values (specified as optional arguments on the special
runtest script command) are a safety feature designed to prevent
runaway tests from never ending. Normally tests end automatically
the very moment they are done.
<p>
<dt><code><em>logfile</em></code><p><dd>
is an optional log file which will receive a copy of
all messages displayed on the control panel
<p>
</dl>
</blockquote>
<p>
Next connect a tn3270 client to the console port (normally port 3270).
The client will be connected to the first 3270 device address specified
in the configuration file (this should be the master console address).
If your master console is a 1052 or 3215, connect a telnet client
instead of a tn3270 client.
<p>
Now you can enter an ipl command from the control panel.
<p><br>
<hr width="50%">
<h4 class="skiplogo" id="keyboard">Using the keyboard</h4>
<p>
The main Hercules screen contains a scrollable list of messages with a command
input area and system status line at the bottom of the screen.
<p>
To scroll through the messages, use either the Page Up or Page Down keys,
the Ctrl + Up Arrow or Ctrl + Down Arrow keys, or the Home or End and/or
the Ctrl + Home or Ctrl + End keys.
<p>
Use the Insert key to switch between insert and overlay mode when typing in
the command input area. Use the Home and End keys to move to the first or
last character of the command you are typing, or the use the left/right arrow keys
to move to a specific character. Use the Escape key to erase the input area.
<p>
Pressing Escape when the command input area is already empty causes the screen
to switch to the semi-graphical "New Panel" display mode, which shows the overall
status of the system and devices.
<p>
When in the semi-graphical "New Panel" display mode there is no command input
area. Instead, single character "hot keys" are used to issue some of the more
common functions such as starting or stopping the CPU. The hot-keys are those
which are highlighted. Pressing the '?' key displays brief help information
on how to use the semi-graphical panel.
<br /><br />
<TABLE border=1 cellpadding=5 align="center" width="70%">
<THEAD>
<TR>
<TH colspan=2><big>Normal cursor handling</big>
</TH>
</TR>
<TR>
<TH width="25%">Key</TH>
<TH>Action</TH>
</TR>
</THEAD>
<TBODY>
<TR>
<TD>
Esc
</TD>
<TD>
Erases the contents of the command input area.
If the command input area is already empty,
switches to semi-graphical New Panel.
</TD>
</TR>
<TR>
<TD>
Del
</TD>
<TD>
Deletes the character at the cursor position.
</TD>
</TR>
<TR>
<TD>
Backspace
</TD>
<TD>
Erases the previous character.
</TD>
</TR>
<TR>
<TD>
Insert
</TD>
<TD>
Toggles between insert mode and overlay mode.
</TD>
</TR>
<TR>
<TD>
Tab
</TD>
<TD>
Attempts to complete the partial file name at the
cursor position in the command input area. If more
than one possible file exists, a list of matching
file names is displayed.
</TD>
</TR>
<TR>
<TD>
Home
</TD>
<TD>
Moves the cursor to the start of the input in the
command input area. If the command input area is
empty, scrolls the message area to the top.
</TD>
</TR>
<TR>
<TD>
End
</TD>
<TD>
Moves the cursor to the end of the input in the
command input area. If the command input area is
empty, scrolls the message area to the bottom.
</TD>
</TR>
<TR>
<TD>
Page Up
</TD>
<TD>
Scrolls the message area up one screen.
</TD>
</TR>
<TR>
<TD>
Page Down
</TD>
<TD>
Scrolls the message area down one screen.
</TD>
</TR>
<TR>
<TD>
Up arrow
</TD>
<TD>
Recalls previous command into the input area.
</TD>
</TR>
<TR>
<TD>
Down arrow
</TD>
<TD>
Recalls next command into the input area.
</TD>
</TR>
<TR>
<TD>
Right arrow
</TD>
<TD>
Moves cursor to next character of input area.
</TD>
</TR>
<TR>
<TD>
Left arrow
</TD>
<TD>
Moves cursor to previous character of input area.
</TD>
</TR>
<TR>
<TD>
Ctrl + Up arrow
</TD>
<TD>
Scrolls the message area up one line.
</TD>
</TR>
<TR>
<TD>
Ctrl + Down arrow
</TD>
<TD>
Scrolls the message area down one line.
</TD>
</TR>
<TR>
<TD>
Ctrl + Home
</TD>
<TD>
Scrolls the message area to the top.
</TD>
</TR>
<TR>
<TD>
Ctrl + End
</TD>
<TD>
Scrolls the message area to the bottom.
</TD>
</TR>
</TBODY>
</TABLE>
<br /><br />
The following additional keyboard functions are effective when the
Hercules Extended Cursor Handling feature (OPTION_EXTCURS) is activated
at compile time.
At present, this feature is activated on the Windows platform only:
<br /><br />
<TABLE border=1 cellpadding=5 align="center">
<TABLE border=1 cellpadding=5 align="center" width="70%">
<THEAD>
<TR>
<TH colspan=2><big>Extended cursor handling</big>
</TH>
</TR>
<TR>
<TH width="25%">Key</TH>
<TH>Action</TH>
</TR>
</THEAD>
<TBODY>
<TR>
<TD>
Alt + Up arrow
</TD>
<TD>
Moves cursor up one row.
</TD>
</TR>
<TR>
<TD>
Alt + Down arrow
</TD>
<TD>
Moves cursor down one row.
</TD>
</TR>
<TR>
<TD>
Alt + Right arrow
</TD>
<TD>
Moves cursor right one column.
</TD>
</TR>
<TR>
<TD>
Alt + Left arrow
</TD>
<TD>
Moves cursor left one column.
</TD>
</TR>
<TR>
<TD>
Tab
</TD>
<TD>
If cursor is outside the command input area,
moves cursor to the start of the input in the
command input area.
Otherwise behaves as described in previous table.
</TD>
</TR>
<TR>
<TD>
Home
</TD>
<TD>
If cursor is outside the command input area,
moves cursor to the start of the input in the
command input area.
Otherwise behaves as described in previous table.
</TD>
</TR>
<TR>
<TD>
End
</TD>
<TD>
If cursor is outside the command input area,
moves cursor to the end of the input in the
command input area.
Otherwise behaves as described in previous table.
</TD>
</TR>
</TBODY>
</TABLE>
<p>
<h4 class="skiplogo" id="commands">Panel commands</h4>
<p>
The following is what is displayed on the Hercules harware console (HMC)
in response to the '?' command being entered. Please note that it may not
be completely accurate or up-to-date. Enter the '?' command for
yourself for a more complete, accurate and up-to-date list of supported
panel commands:
<p>
<pre>
Command Description
------- -----------------------------------------------
!message *SCP priority message
# Silent comment
$locate Display sysblk, regs or hostinfo
$test *Your custom command (*DANGEROUS!*)
$zapcmd *Enable/disable command (*CAREFUL!*)
* Loud comment
.reply *SCP command
? alias for help
aea Display AEA tables
aia Display AIA fields
alrf Command deprecated: Use "archlvl enable|disable|query asn_lx_reuse" instead
ar Display access registers
archlvl *Set Architecture Level
archmode Alias for archlvl
asn_and_l Command deprecated: Use "archlvl enable|disable|query asn_lx_reuse" instead
attach *Configure device
auto_scsi *Command deprecated - Use "SCSIMOUNT"
autoinit *Display/Set automatic create empty tape file switch
automount *Display/Update allowable tape automount directories
b *Set breakpoint
b+ Set breakpoint
b- *Delete breakpoint
cache *Execute cache related commands
cachestat Cache stats command
capping *Set/display capping value
cckd *cckd command
cf *Configure current CPU online or offline
cfall Configure all CPU's online or offline
clocks Display tod clkc and cpu timer
cmdlevel *Display/Set current command group
cmdlvl (alias for cmdlevel)
cmdsep *Display/Set command line separator
cmpscpad *Set/display the CMPSC zero padding value.
cnslport Set console port
codepage *Set/display code page conversion table
conkpalv *Display/alter console TCP keep-alive settings
cp_updt *Create/Modify user character conversion table
cpu *Define target cpu for panel display and commands
cpuidfmt Set format BASIC/0/1 STIDP generation
cpumodel Set CPU model number
cpuprio Set/Display cpuprio parameter
cpuserial Set CPU serial number
cpuverid Set CPU verion number
cr *Display or alter control registers
cscript *Cancels a running script thread
ctc *Enable/Disable CTC debugging
define *Rename device
defstore *Define/Display main and expanded storage values
defsym *Define symbol
delsym *Delete a symbol
detach Remove device
devinit *Reinitialize device
devlist *List device, device class, or all devices
devprio Set/Display devprio parameter
devtmax *Display or set max device threads
diag8cmd Set diag8 command option
ds Display subchannel
dumpdev *Specify bootstrap loader DUMP parameters
ecps:vm *Command deprecated - Use "ECPSVM"
ecpsvm *ECPS:VM Commands
engines Set engines parameter
evm *Command deprecated - Use "ECPSVM"
exec *Execute a Rexx script
exit (Synonym for 'quit')
ext Generate external interrupt
fcb *Display the current FCB (if only the printer is given)
fpc *Display or alter floating point control register
fpr *Display or alter floating point registers
f{+/-}adr Mark frames unusable/usable
g Turn off instruction stepping and start all CPUs
gpr *Display or alter general purpose registers
hao *Hercules Automatic Operator
help *list all commands / command specific help
herclogo *Read a new hercules logo file
hercprio Set/Display hercprio parameter
hst *History of commands
http *Start/Stop/Modify/Display HTTP Server
httpport *Command deprecated - Use "HTTP PORT ..."
httproot *Command deprecated - Use "HTTP ROOT fn"
hwldr *Specify boot loader filename
i Generate I/O attention interrupt for device
iodelay *Display or set I/O delay value
ipending Display pending interrupts
ipl *IPL from device or file
iplc *Command deprecated - use IPL with clear option
k Display cckd internal trace
ldmod *Load a module
legacysen Set legacysenseid setting
loadcore *Load a core image file
loaddev *Specify bootstrap loader IPL parameters
loadparm *Set IPL parameter
loadtext *Load a text deck file
locks *Display internal locks list
log *Direct logger output
logopt *Set/Display logging options
lparname *Set LPAR name
lparnum *Set LPAR identification number
lsdep List module dependencies
lsmod List dynamic modules
mainsize *Define/Display mainsize parameter
manufactu Set STSI manufacturer code
maxcpu Set maxcpu parameter
maxrates *Display highest MIPS/SIOS rate or set interval
message *Display message on console a la VM
model *Set/Query STSI model code
modpath Set module load path
mounted_t *Control tape initialization
msg Alias for message
msglevel *Display/Set current Message Display output
msglvl Alias for msglevel
msgnoh Similar to "message" but no header
mt *Control magnetic tape operation
numcpu Set numcpu parameter
numvec Set numvec parameter
ostailor *Tailor trace information for specific OS
panrate *Display or set rate at which console refreshes
pantitle *Display or set console title
pgmprdos *Set LPP license setting
pgmtrace *Trace program interrupts
plant Set STSI plant code
pr Display prefix register
psw *Display or alter program status word
ptp *Enable/Disable PTP debugging
ptt *Set or display internal trace
qcpuid *Display cpuid
qd Query dasd
qpfkeys Display the current PF Key settings
qpid Display Process ID of Hercules
qports Display TCP/IP ports in use
qproc Display processors type and utilization
qstor Display main and expanded storage values
quiet *Toggle automatic refresh of panel display data
quit *Terminate the emulator
r *Display or alter real storage
restart Generate restart interrupt
resume Resume hercules
rexx *display Rexx interpreter settings
rmmod Delete a module
s *Instruction stepping
s+ *Instruction stepping on
s- Turn off instruction stepping
s? *Instruction stepping query
savecore *Save a core image to file
sclproot *Set SCLP base directory
scpecho *Set/Display option to echo to console and history of scp replys
scpimply *Set/Display option to pass non-hercules commands to the scp
script *Run a sequence of panel commands contained in a file
scsimount *Automatic SCSI tape mounts
sf+dev Add shadow file
sf-dev Delete shadow file
sfc Compress shadow files
sfd Display shadow file stats
sfk *Check shadow files
sh *Shell command
shcmdopt Set diag8 sh option
shrd shrd command
shrdport Set shrdport value
sizeof Display size of structures
srvprio Set/Display srvprio parameter
ssd *Signal shutdown
start *Start CPU (or printer/punch device if argument given)
startall Start all CPU's
stop *Stop CPU (or printer/punch device if argument given)
stopall Stop all CPU's
store Store CPU status at absolute zero
suspend Suspend hercules
symptom Alias for traceopt
syncio Display syncio devices statistics
sysclear *System Clear Reset manual operation
sysepoch Set sysepoch parameter
sysreset *System Reset manual operation
s{+/-}dev Turn CCW stepping on/off
t *Instruction trace
t+ *Instruction trace on
t- Turn off instruction tracing
t? *Instruction trace query
timerint *Display or set timers update interval
tlb Display TLB tables
toddrag Display or set TOD clock drag factor
todprio Set/Display todprio parameter
traceopt *Instruction trace display options
tt32 *Control/query CTCI-WIN functionality
tzoffset Set tzoffset parameter
t{+/-}CKD Turn CKD_KEY tracing on/off
t{+/-}dev Turn CCW tracing on/off
u *Disassemble storage
uptime Display how long Hercules has been running
v *Display or alter virtual storage
version Display version information
xpndsize *Define/Display xpndsize parameter
yroffset Set yroffset parameter
(*) Enter "<a href="#morehelp">help <command></a>" for more info.
</pre>
<p>
The <em>ipl</em> command may also be used to perform a load from cdrom or
server. For example if a standard SuSE S/390 Linux distribution CD is loaded
and mounted on /cdrom for example, this cdrom may then be ipl-ed by:
<em>ipl /cdrom/suse.ins</em>
<p>
The <em>attach</em> and <em>detach</em> commands are used to dynamically
add or remove devices from the configuration,
and the <em>define</em> command can be used to alter the device number
of an existing device.
<p>
The <em>devinit</em> command can be used to reopen an existing device.
The <em>args</em> (if specified) override the arguments
specified in the configuration file for this device.
The device type cannot be changed and must not be specified.
This command can be used to rewind a tape, to mount a new tape or
disk image file on an existing device, to load a new card deck
into a reader, or to close and reopen a printer or punch device.
<p>
In single-step mode, pressing the enter key will advance to the
next instruction.
<p>
There is also an alternate semi-graphical control panel. Press Esc to
switch between the command line format and the semi-graphical format.
Press ? to obtain help in either control panel.
<p>
When a command is prefixed with '-', the the command will not be redisplayed at
the console. This can be used in scripts and is also used internally when commands
are to be invoked without being redisplayed at the panel.
<br /><br />
<h5 id="morehelp">Additional Command Help</h5><br /><br />
Some commands also offer additional help information regarding their syntax,
etc. Enter "<tt>help <i><command name></i></tt>" to display
this additional help information. (Note: not every command supports additional help)
<br /><br />
<hr width="50%">
<h4 class="skiplogo" id="RCFILE">The hercules.rc (run-commands) file</h4>
</a>
<p>
Hercules also supports the ability to automatically execute panel commands
upon startup via the 'run-commands' file. If the run-commands file
is found to exist when Hercules starts, each line contained within it is
read and interpreted as a panel command exactly as if the command were
entered from the HMC system console.
<p>
The default filename for the run-commands file is "hercules.rc", but may be
overridden by setting the "<tt><b>HERCULES_RC</b></tt>" environment variable to the
desired filename.
<p>
Except for the 'pause' command (see paragraph further below), each command
read from the run-commands file is logged to the console preceded by a '> '
(greater-than sign) character so you can easily distinguish between panel
commands entered from the keyboard from those entered via the .rc file.
<p>
Lines starting with '<tt>#</tt>' are treated as "silent comments" and are
thus not logged to the console. Line starting with '<tt>*</tt>' however are
treated as "loud comments" and <i>will</i> be logged.
<p>
In addition to being able to execute any valid panel command (including the
'sh' shell command) via the run-commands file, an additional
'<tt><b>pause <i>nnn</i></b></tt>' command is supported in order to introduce
a brief delay before reading and processing the next line in the file. The
value <tt><i>nnn</i></tt> can be any number from 0.001 to 999.0 and specifies
the number of seconds to delay before reading the next line. Creative use of
the run-commands file can completely automate Hercules startup.
<br /><br />
<hr width="50%">
<h4 class="skiplogo" id="HAO">The "Hercules Automatic Operator" (HAO) Facility</h4>
</a>
<p>
The Hercules Automatic Operator (HAO) feature is a facility which can
automatically issue panel commands in response to specific messages
appearing on the Hercules console.
<p>
To use the Hercules Automatic Operator facility, you first define a "rule"
consisting of a "target" and an 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 its associated command is automatically issued.
<p>
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.
<h5>Defining a Rule</h5>
<p>
To define a HAO rule, enter the command:
<pre>
hao tgt <i>target</i>
</pre>
<p>
to define the rule's "target" match pattern
followed by the command:
<pre>
hao cmd <i>command</i>
</pre>
<p>
to define the rule's associated panel-command.
<p>
The <i>target</i> 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.
<p>
The associated <i>command</i> is whatever valid Hercules panel command you
wish to issue in response to a message being issued that matches the given
<i>target</i> pattern.
<h5>Substituting substrings in the command</h5>
<p>
The <i>command</i> may contain 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.
<p>
The following special variables are recognized:
<ul>
<li><code>$1</code> to <code>$9</code> -
the text which matched the 1st to 9th capturing
group in the target regular expression
<li><code>$`</code> - the text preceding the regular expression match
<li><code>$'</code> - the text following the regular expression match
<li><code>$$</code> - replaced by a single dollar sign
</ul>
<p>
Note that substitution of a $<i>n</i> variable does not occur if there are
fewer than <i>n</i> capturing groups in the regular expression.
<p>
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:
<pre>
hao tgt HHCTE014I 3270 device ([0-9A-F]{3,4})
hao cmd i $1
</pre>
<p>
Another example, shown below, illustrates how the dot matrix display of a
3480 tape unit might be used to implement an automatic tape library:
<pre>
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
</pre>
<h5>Other commands and limitations</h5>
<p>
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 <i>nnn</i>' command to delete the specific rule identified by
<i>nnn</i> (all rules are assigned numbers as they are defined and are thus
identified by their numeric value). Optionally, you can delete all defined or
partially defined rules by issuing the command 'hao clear'.
<p>
The current implementation limits the total number of defined rules to 64.
This limit may be raised by increasing the value of the HAO_MAXRULE
constant in hao.c and rebuilding Hercules.
<p>
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.
<br /><br />
<hr>
<h3 class="skiplogo" id="support">Technical Support</h3>
<P>
For technical support, please see our <a href="hercsupp.html">Technical Support</a> web page.
<br /><br />
<hr>
<br />
<center>
<a href="index.html"><img src="images/back.gif" border=0 alt="back"></a>
</center>
<br />
</center>
</div>
</body>
</HTML>