forked from hercules-390/html
-
Notifications
You must be signed in to change notification settings - Fork 3
/
Copy pathhercinst.html
1475 lines (1257 loc) · 56.9 KB
/
hercinst.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
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 3.0//EN" "http://www.w3.org/TR/html4/loose.dtd">
<HTML><HEAD><TITLE>
Hercules: Installation and Operation
</TITLE>
<LINK REL=STYLESHEET TYPE="text/css" HREF="hercules.css">
<link rel="shortcut icon" href="images/favicon.ico" />
<link rel="icon" href="images/favicon.ico" />
</HEAD><BODY BGCOLOR="#ffffcc" TEXT="#000000" LINK="#0000A0" VLINK="#008040" ALINK="#000000">
<h1>Hercules Version 4: Installation and Operation</h1>
<p><hr>
<h2>Contents</h2>
<blockquote>
<p>
<a href="#install">Building and Installing</a>
<ul>
<li><a href="#buildwin">Building from source on Windows</a>
<ul>
<li><a href="#instbinary">Windows Pre-built binaries</a>
</ul>
<li><a href="#buildmac">Building from source on Mac OS X</a>
<li><a href="#buildnix">Building from source on Linux and macOS (High Sierra and newer)</a>
</ul>
</p>
<p>
<a href="#config">Configuration</a>
</p>
<p>
<a href="#dasd">Creating DASD volumes</a>
</p>
<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">HAO ("Hercules Automatic Operator")</a>
</ul>
</p>
<p>
<a href="#support">Technical Support</a>
</p>
</blockquote>
<p><hr><a name="install"></a>
<h2>Building and Installing</h2>
<p>
By far <i><u>easiest</u></i> and most direct way to build Hercules is
to use Bill Lewis's fantastic
<b><i><u>Hercules Helper</u></i></b> tool, and <b><i>not</i></b> the below manual method.
<p>
<b><i><u>Hercules Helper</u></i></b>
<i>
(for both <a href="https://github.com/wrljet/hercules-helper-windows">Windows</a>
and <a href="https://github.com/wrljet/hercules-helper">non-Windows</a>)
</i>
completely automates the entire build process of downloading and installing all of the
needed pieces and running all of needed commands to create a working Hercules. Simply
download Bill's tool and enter a few simple commands, and within minutes you should have
a working Hercules on your system.
<a name="instsource"></a>
<a name="buildwin"></a>
<h3>Building from source - Windows</h3>
<p>
If you wish to build Hercules yourself <b>manually</b> however, the procedure is as follows:
<br><br>
<ol>
<li>Clone the <b><a href="https://github.com/sdl-hercules-390/hyperion">Hercules source code git repository</a></b>
<i>(recommended)</i>, or download the
<a href="https://github.com/sdl-hercules-390/hyperion/archive/master.zip">source code .ZIP file</a>
from Github <i>(discouraged!)</i>.
<p><pre>
git clone https://github.com/SDL-Hercules-390/hyperion.git <directory-name>
</pre><p>
If you don't have <code>git</code> on your system, you will need to <a href="https://gitforwindows.org/">install it</a>.
<p>
<em><b>Note:</b> By downloading the source code .zip file <i>(discouraged!)</i>
or by cloning the repository <i>(recommended)</i>
you agree to the terms of the Hercules <a href="herclic.html">Q Public Licence</a>.</em>
<br />
<li>
Hercules for Windows is built using the Microsoft Visual C/C++ (MSVC) compiler.
Fish has updated manual build instructions for VS2015 and greater (as well as VS2008 too) on his
<a href="http://www.softdevlabs.com/hercules-vs2015-build.html">MSVC Hercules Build Instructions</a>
web page, although as mentioned above, the <i>by far</i> easiest most reliable way to build Hercules
on Windows is to use Bill Lewis's
"<a href="https://github.com/wrljet/hercules-helper-windows"><b>Hercules Helper for Windows</b></a>"
tool, which is designed to build Hercules using much more current versions of Visual Studio.
<br /><br />
<li>Be sure to read the <a href="https://sdl-hercules-390.github.io/html/hercrnot.html">Release Notes</a>
with every new release too, which contains important late-breaking information about each new release.
<br /><br />
</ol>
</p>
<a name="instbinary"></a>
<h3>Windows pre-built binaries:</h3>
<ol>
<li>Download one of the
<a href="https://github.com/SDL-Hercules-390/hyperion/releases">pre-built Official Release binaries</a>
from
<a href="https://github.com/SDL-Hercules-390/hyperion">GitHub</a>.
<br />
<br />
<li>(Optional) You might also want to install Fish's
<a href="http://www.softdevlabs.com/hercgui">Hercules GUI for Windows</a>
and/or one or more of his other <a href="http://www.softdevlabs.com/index.html">Hercules products</a>.<br /><br />
</ol>
<a name="buildmac"></a>
<h3>Building from source - Mac OS X</h3>
<p><em><b>Important - Not Recently Tested. May be obsolete.</b></em>
<ol>
<li>Install <b>Xcode</b> from the
<a href="http://itunes.apple.com/app/xcode/id497799835">
App Store</a>.
<br />
<br />
<li>Install <b>Homebrew</b> using the procedure described
at <a href="http://brew.sh/">http://brew.sh/</a>
<br />
<br />
<li>Use these commands to install pre-requisite software:<br />
<br><code>brew install gnu-sed</code>
<br />
<br />
<a name="buildnix"></a>
<li>Proceed with <i>Building from source - Linux and macOS</i> below.<br /><br />
</ol>
<a name="instnixmac"></a>
<h3>Building from source - Linux and macOS (High Sierra and newer)</h3>
<p>
<em><b>Important: Please read everything before doing anything. Don't be bashful about asking for help. </b></em>
<p>
<em><b>Important:</b></em>
You must use at least version 6.2.0 of the gcc compiler and associated glibc2 library.
Refer to the <a href="hercfaq.html#3.04">
Hercules Frequently-Asked Questions</a> page for required
compiler and other software levels.<br />
<ol>
<li>Download the
<a href="https://github.com/sdl-hercules-390/hyperion/archive/master.zip">source code .ZIP file</a>
from Github, or even better, <b><a href="https://github.com/sdl-hercules-390/hyperion">clone the repository</a>.</b>
(Note: building from the source code .zip file is <i><u>strongly discouraged</u></i>. Instead,
it is <i><u>highly recommended</u></i> that you clone the git repository and build from that instead.
This allows the exact version of the source code to be determined, which is very helpful should
a problem need to be diagnosed.)
<p><pre>
git clone https://github.com/SDL-Hercules-390/hyperion.git <directory-name>
</pre><p>
<em><b>Note:</b> By downloading the .zip file (or cloning the repostiory) you agree to the terms
of the <a href="herclic.html">Q Public Licence</a>.</em>
<br />
<li>Be sure to read the <a href="https://sdl-hercules-390.github.io/html/hercrnot.html">Release Notes</a>
with every new release, which contains important late-breaking information about each new release.
<br />
<br />
<li>Install the required packages appropriate for your system.
<p><ul>
<li>Debian / Ubuntu / Mint / etc
<p><code>
sudo apt-get -y install git wget time<br>
sudo apt-get -y install build-essential cmake flex gawk m4 autoconf automake libtool-bin libltdl-dev<br>
sudo apt-get -y install libbz2-dev zlib1g-dev<br>
sudo apt-get -y install libcap2-bin
</code>
<p><i>Note: For Regina REXX to run the included tests:</i>
<p><code>
sudo apt-get -y install libregina3-dev
</code>
<li>Elbrus Linux (similar to Debian)
<p><code>
sudo apt-get -y install git wget time<br>
sudo apt-get -y install build-essential cmake flex gawk m4 autoconf automake libtool<br>
sudo apt-get -y install bzip2 zlib<br>
sudo apt-get -y install libcap
</code>
<li>Arch / Manjaro
<p><code>
sudo pacman -S --needed --noconfirm git wget<br>
sudo pacman -S --needed --noconfirm base-devel make cmake flex gawk m4 autoconf automake<br>
sudo pacman -S --needed --noconfirm bzip2 zlib
</code>
<li>Fedora
<p><code>
sudo dnf -y install git wget<br>
sudo dnf -y install gcc make cmake flex gawk m4 autoconf automake libtool-ltdl-devel<br>
sudo dnf -y install bzip2-devel zlib-devel
</code>
<li>CentOS / AlmaLinux / Rocky Linux 8+ / Red Hat RHEL 9
<p><code>
sudo yum -y install git wget time<br>
sudo yum -y install gcc make cmake flex gawk m4 autoconf automake libtool-ltdl-devel<br>
sudo yum -y install bzip2-devel zlib-devel
</code>
<p>
<p><i>Note: On CentOS 9, the following command is required <b>before</b> installing the packages:</i>
<p><code>
sudo yum config-manager --set-enabled crb
</code>
<p>
<p><i>Note: On Red Hat RHEL 9, the following command is required <b>before</b> installing the packages:</i>
<br>(refer <a href="https://www.redhat.com/sysadmin/install-epel-linux">here</a> for more information)
<p><code>
sudo subscription-manager repos --enable codeready-builder-for-rhel-9-$(arch)-rpms
</code>
<li>CentOS 7
<p><code>
sudo yum -y install git wget<br>
sudo yum -y install gcc make flex gawk m4 autoconf automake libtool-ltdl-devel<br>
sudo yum -y install bzip2-devel zlib-devel
</code>
<p><i>Note: On CentOS 7, there is no package for CMAKE 3.x, it must be built from source.</i>
<li>openSUSE (15.1+)
<p><code>
sudo zypper install -y git<br>
sudo zypper install -y -t pattern devel_basis autoconf automake cmake flex gawk m4 libtool<br>
sudo zypper install -y -t pattern bzip2 libz1 zlib-devel<br>
sudo zypper install -y libcap-progs
</code>
<li>Apple Darwin (macOS High Sierra, Mojave, Catalina, Big Sur, etc.) with Homebrew
<p><code>
xcode-select --install<br>
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"<br>
<p>
brew install wget gsed<br>
brew install cmake autoconf automake libtool<br>
<!-- ( flex gawk m4 bzip2 zlib ) -->
</code>
<p><i>Note: So configure/make will find ltdl.h and libltdl:</i>
<p><code>
export CFLAGS="$CFLAGS -I$(find $(brew --cellar libtool) -type d -name "include" | sort -n | tail -n 1)"<br>
export LDFLAGS="$LDFLAGS -L$(find $(brew --cellar libtool) -type d -name "lib" | sort -n | tail -n 1)"
</code>
<p><i>And include these options to configure:</i>
<p><code>
--disable-getoptwrapper<br>
--without-included-ltdl
</code>
<li>Apple Darwin (macOS Big Sur) with MacPorts
<p>Information on installing MacPorts may be found
<a href="https://guide.macports.org/chunked/installing.macports.html">here</a>.
<p><code>
sudo port install wget gsed<br>
sudo port install cmake autoconf automake libtool
</code>
<p><i>Note: So configure/make will find ltdl.h and libltdl:</i>
<p><code>
export CFLAGS=-I/opt/local/include LDFLAGS=-L/opt/local/lib
</code>
<li>FreeBSD
<p><code>
sudo pkg install -y bash git wget<br>
sudo pkg install -y gmake autoconf automake cmake flex gawk m4 libltdl<br>
sudo pkg install -y bzip2
</code>
<p><i>Note: Bash is required by parts of the build apparatus.</i>
<p><i>Note: So configure/make will find ltdl.h and libltdl:</i>
<p><code>
export CFLAGS=-I/usr/local/include LDFLAGS=-L/usr/local/lib
</code>
<li>OpenBSD is not currently supported
<p>
</ul>
<li>Verify you have all of the correct versions of the more important packages installed:
<p><code>./util/bldlvlck</code>
<p>
Please note that SDL Hyperion comes pre-delivered with an already pre-generated
<code>./configure</code> script, so doing a <code>./autogen.sh</code> is
not necessary and is in fact now strongly discouraged.
An autogen would only be necessary if you were to manually make some changes
to the Hercules default <code>Makefile.am</code> and/or <code>configure.ac</code>
files (which under normal circumstances you should never need to do).
<p>
<li>Download and build all <b>External Packages</b>, if needed:
<br /><br />
Hercules links with several pre-built "External Package" static link libraries
that have been pre-built for you and come distributed with Hercules (i.e. they
are a part of the Hercules repository).
<br /><br />
Currently all of the external package static link libraries for the Intel x86
(32-bit) and x64 (64-bit) architectures for both Windows and Linux for both
normal optimized Release builds as well as unoptimized Debug builds are already
provided as part of the distribution. Thus to build Hercules you should not
need to do anything special. Simply build Hercules just as you normally would.
<br /><br />
In some unusual situations however, you MIGHT need to rebuild ALL existing
external packages for your particular system. Exactly what those situations
are and what causes them to occur is unclear, but one thing is certain: it
will never hurt to build all of the external packages anyway just to be safe.
<br /><br />
If you wish to modify or debug any of the external packages themselves (or need
to build a non-Intel x86/x64 architecture build of Hercules however, such as arm, mips,
ppc, sparc, xscale, etc), then you will need to manually build each of the
external packages first in order to create the static link libraries that Hercules
will need to link with, before you can then build Hercules.
<br /><br />
For more detailed External Package build information please refer to the
<a href="https://github.com/sdl-hercules-390/hyperion/blob/master/readme/README.EXTPKG.md">README.EXTPKG</a>
document.
<p>
<li>Configure Hercules for your system:
<p><code>./configure</code>
<p>
By default, the configure script will attempt to guess appropriate
compiler optimization flags for your system. If its guesses
turn out to be wrong, you can either specify your own optimization
flags with <code><nobr>--enable-optimization=FLAGS</nobr></code>
(<i>preferred</i>) or else as a last resort disable all optimization
by passing the <code><nobr>--disable-optimization</nobr></code> option
instead (<i><b>not</b> recommended</i>). For additional configuration
options, run: <code>./configure <nobr>--help=short</nobr></code>.
<p>For Apple macOS, these additional configure switches are recommended:
<p><code>
--disable-getoptwrapper<br>
--without-included-ltdl
</code>
<br />
<li>Build the executables:
<p><code>make</code>
<p>
<li>(Optional) Install the programs:
<p>
<code>sudo make install</code>
<br />
<p>
This is an optional step because once Hercules is built, you should be able to
run Hercules directly from the Hercules build directory itself without needing
to install anything beforehand. But if you want to officially install it somewhere,
then by all means do so.
<p>
It should be mentioned however, that if you do decide to run directly out of the
build directory, you should first set the 'cap_sys_nice' capabilities on the
Hercules executables and start Hercules as root. This will allow Hercules to
properly set the priorities of its internal threads:
<pre>
sudo setcap 'cap_sys_nice=eip' ./hercules
sudo setcap 'cap_sys_nice=eip' ./herclin
sudo setcap 'cap_net_admin+ep' ./hercifc
</pre>
You <i>don't</i> need to do this if you do <code>sudo make install</code> however
since the makefile does this for you. You only need to do this when you decide
to <i>not</i> install the results of the build and run directly out of the build
directory instead.
</ol>
<p><hr><a name="config"></a>
<h2>Configuration</h2>
<p>
You will need to amend the configuration file
<em><b>hercules.cnf</b></em> to reflect your device layout and intended
mode of operation (S/370, ESA/390, or z/Architecture).
See the <a href="hercconf.html">Hercules Configuration File</a> page for
a complete description.
<p><hr><a name="dasd"></a>
<h2>Creating DASD volumes</h2>
<p>
The <a href="hercload.html">Creating Hercules DASD</a> page
describes various methods of creating and loading virtual DASD
volumes. The compressed CKD DASD support is described in <a
href="cckddasd.html">this page</a>.
<p><hr><a name="operating"></a>
<h2>Operating Procedure</h2>
<center>
<table width=95%>
<tr><td>
<p class="warning">
<i><u>Note</u>! If you intend to run any licensed software on your PC
using Hercules, it is <u>your</u> responsibility to ensure that
you do not violate the software vendor's licensing terms!</i></p>
</td></tr>
<tr><td>
</td></tr>
<tr><td>
<p class="box"><i>
<b>Note:</b> Hercules requires privileged access to your host's
networking devices in order for Hercules networking to work properly.
If your configuration contains any <b>networking devices</b>, then
Hercules must be started with <b>Administrative (root) privileges</b>.
If Hercules is not started with Administrative (root) privileges then
initialization of your networking devices will fail and your guest's
networking will not work properly. If your guest does not need access
to your host's network Hercules should be run as a normal unprivileged
user (the default).</i></p>
</td></tr>
</table>
</center>
<p>
Hercules can operate in either of two modes: (semi-)graphical "panel"
mode or simple non-graphical standard command-line mode.
<p>
The default semi-graphical "panel" mode of operation is invoked by the
"<b>hercules.exe</b>" executable, and the non-graphical standard command-line
mode by the "<b>herclin.exe</b>" executable. They are both exactly identical
except for how the terminal screen is managed.
<p>
In the normal (default) semi-graphical "panel" mode, <b>hercules.exe</b> draws
to screen directly itself, and does not rely on any terminal manager
functionality (Terminal or Command-Prompt program). It paints (draws)
messages and other information (such as its command line and CPU status
line) on specifc screen lines starting at specific columns, etc:
<br><br>
<center>
<img src="images/herc-panel.jpg"><br><br><b>hercules.exe</b> managed Hardware Machine Console (HMC)
</center>
<p><br>
It relies on certain keystrokes (such as the PageUp and PageDown keys,
etc) to perform actions such as displaying previously issued messages
and switching to its alternate semi-graphical display panel via the <b>Esc.
key</b> (which shows an overal summary of the machine's state, such as its
current set of register values, list of devices, etc):
<br><br>
<center>
<img src="images/herc-panel2.jpg"><br><br><b>hercules.exe</b> managed semi-graphical panel
</center>
<p><br>
When started in standard command-line mode via "<b>herclin.exe</b>", the terminal
screen is managed completely by your host operating system's terminal
management software. Hercules does not paint the screen itself at all. It simply
issues messages to "stdout" just like any other command-line program and your operating
system's terminal management software decides where on the screen that line
will be displayed. Additionally, Hercules does not read directly from the
command-ine itself either. Instead, it simply reads from "stdin" and processes
the commands it reads. Your host operating system's terminal manager is in charge
of managing the command-line, not Hercules:
<br><br>
<center>
<img src="images/herclin.jpg"><br><br><u><i>Unmanaged</i></u> "<b>herclin.exe</b>" terminal
screen,<br> scrolled back several screens to see previously issued terminal commands.
</center>
<p><br>
In standard "<b>herclin.exe</b>" command-line mode, Hercules operates just like any other
normal command-line program, and you can use the Terminal's scroll bar (if it has
one) and/or your mouse's scroll wheel to scroll the screen backward or forward to
see previously issued mesages and/or commands and their responses. Your host
operating system's terminal manager is in charge of painting the screen and reading
the command line, not Hercules.
<a name="arguments"></a>
<h4>Command line arguments</h4>
<p>
To start Hercules in the default "panel" operating mode, enter this command
at the host's command prompt:
<blockquote><code><pre>
hercules [ -f <em>filename</em> ] | [ --config=<em>filename</em> ]
[ -o <em>logfile</em>] | [ --output=<em>logfile</em> ] | [ --logfile=<em>logfile</em> ]
[ -r <em>rcfile</em> ] | [ --rcfile=<em>rcfile</em> ]
[ -b <em>logofile</em> ] | [ --herclogo=<em>logofile</em> ]
[ -d ] | [ --daemon ]
[ -e ] | [ --externalgui ]
[ -p <em>modpath</em> ] | [ --modpath=<em>modpath</em> ]
[ -l <em>modname</em> ] ... | [ --ldmod=<em>modname</em> ] ...
[ -s <em>symbol=value</em> ] ... | [ --defsym=<em>symbol=value</em> ] ...
[ -v ] | [ --verbose ]
[ -h ] | [ --help[=type] ]
[ -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. If the value "<b>none</b>" is specified as the
name of the configuration file, then Hercules is started without a
configuration file using internal default values and no devices.
Alternatively, specifying the filename as "<code>NUL</code>" on
Windows or "<code>/dev/null</code>" on Linux means the same thing
as specifying "<b>none</b>".
<p>
<dt><code><em>logfile</em></code><p><dd>
is the name of the optional log file. A log file receives a copy
of all messages displayed on the Hercules control panel.
<i><b>PLEASE NOTE:</b> providing a logfile is extremely important
for bug reporting and problem analysis purposes! It is <b>strongly
recommended</b> that you <u>always</u> specify this option!</i>
<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. If not specified, the value of the "<code>HERCULES_RC</code>"
environment variable is used. If no environment variable is defined,
the default value "hercules.rc" is used. If the default "hercules.rc"
file is not found, then the value "<b>none</b>" is used, indicating
an .rc file will not be used.
<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>--daemon</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>--externalgui</em></em></code><p><dd>
indicates Hercules is to be controlled by an External GUI.
<p>
<dt><code><em>modpath</em></code><p><dd>
is the directory from which dynamic modules are to be loaded.
This option overrides both the
<code><a href="hercconf.html#MODPATH">MODPATH</a></code>
configuration file statement and system defaults.
The system default varies depending on the host platform
where Hercules is being run.
<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>--verbose</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>--help[=type]</em></code><p><dd>
displays help regarding the syntax of command-line arguments and,
optionally, other information as well if the optional help
<code>type</code> is also specified.
<p>
The optional <code>type</code> value identifies what type of help
you want to display. Valid values are: <code>short</code>,
<code>long</code>, <code>version</code> or <code>build</code>.
Additionally, <code>all</code> and <code>full</code> are also
accepted as aliases for <code>long</code>.
<p>
The <code>short</code> help option displays just the syntax of the
the command line arguments. The <code>version</code> help option
displays version information. The <code>build</code> option displays
some of the more important optional features that Hercules was
either built with or without. The <code>long</code>, <code>all</code>
and <code>full</code> options displays all three types. The default
is <code>short</code> (i.e. only the command-line syntax is shown).
<p>
<dt><code><em>--test[=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 the name of the optional <i>(but highly recommended!)</i> log file.
The log file receives a copy of all messages displayed on the
control panel and is extremely important to have for problem
analysis and bug reporting.
<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%">
<a name="keyboard">
<h4>Using the keyboard</h4>
<p>
In the default "panel" operating mode, 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. (see further above)
<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>