Installing and Operating Hercules

Installation Procedure

Building from source

These instructions apply to the Linux version. Volker Bandke has instructions on how to build the Win32 version at http://www.bsp-gmbh.com/hercules/nude_w32.html.

Download the distribution file hercules-1.71.tar.gz [ http://www.conmicro.cx/hercules/hercules-1.71.tar.gz ]
Notes:
1. By downloading this file you agree to the terms of the Q Public Licence [ http://www.conmicro.cx/hercules/herclic.html ].
2. IE4 may report "problem with security settings or file does not exist" when downloading this file. I do not know why. If you experience this problem, use IE5 or Netscape Navigator instead.
Use these commands to unzip the distribution file:
```
tar xvzf ../hercules-1.71.tar.gz
cd hercules-1.71
```
Build the executable files:
make [HOST_ARCH=arch]
The HOST_ARCH argument is optional. It specifies the machine architecture, for setting options on the C compiler. Possible values are:
- i386: Intel 386 and above. No architecture optimizations are done.
- i586: Pentium and above. If specified, the resulting package will not run on 386 or 486 systems.
- i686: Pentium Pro and Pentium II. If specified, the resulting package will not run on 386, 486, or Pentium systems.
- Anything else will remove the Intel-specific compiler flag.
The default is i586, since most Hercules users appear to be running Pentiums. If building for an Intel-based system, you must not give HOST_ARCH an undefined value, as this will cause Hercules to break in weird and wonderful ways. If, on the other hand, you are building for a non-Intel platform, you must give HOST_ARCH a non-Intel value.
Install the programs: as root,
make install

Important: You must use the egcs compiler and the glibc2 library. Refer to the Hercules Frequently-Asked Questions [ http://www.conmicro.cx/hercules/hercfaq.html#software ] page for required compiler and other software levels.

Installing prebuilt RPMs:

Download the RPM file you want:
- hercules-1.71-1.i686.rpm [ http://www.conmicro.cx/hercules/hercules-1.71-1.i686.rpm ]: Intel Pentium Pro/Pentium II
- hercules-1.71-1.i586.rpm [ http://www.conmicro.cx/hercules/hercules-1.71-1.i586.rpm ]: Intel Pentium
- hercules-1.71-1.i386.rpm [ http://www.conmicro.cx/hercules/hercules-1.71-1.i386.rpm ]: Intel 386
- hercules-1.71-1.alpha.rpm [ http://www.conmicro.cx/hercules/hercules-1.71-1.alpha.rpm ]: Alpha (all flavors)
Install the RPM:
rpm -Uvh RPMfile

This will leave the Hercules executables in /usr/bin, where you can run them from anywhere. Sample configuration files will be placed in /etc/hercules, and the IPLable card deck for the ZZSA standalone utility will be placed in /var/share/hercules.

Configuration Procedure

You will need to amend the configuration file hercules.cnf to reflect your device layout. See the Hercules Configuration File [ http://www.conmicro.cx/hercules/hercconf.html ] page for a complete description.

Creating DASD volumes

The Creating Hercules DASD [ http://www.conmicro.cx/hercules/hercload.html ] page describes various methods of creating and loading virtual DASD volumes. The compressed CKD DASD support is described in this page [ http://www.conmicro.cx/hercules/cckddasd.html ].

Operating Procedure

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.

Loading a standalone program or operating system

To start Hercules in either S/370 mode or ESA/390 mode, enter the appropriate command at the Unix shell prompt:

hercules-370 [-f filename] [> logfile]
hercules-390 [-f filename] [> logfile]

where filename is the name of the configuration file (the default is hercules.cnf), and logfile is an optional log file which will receive a copy of all messages displayed on the control panel.

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.

Now you can enter an ipl command from the control panel.

Panel commands

cpu n   Set target CPU for subsequent commands
psw     Display program status word
gpr     Display general-purpose registers
fpr     Display floating-point registers
cr      Display control registers
ar      Display access registers
pr      Display prefix register
 
rx      Display 64 bytes starting at real address x
rx.n    Display n bytes starting at real address x
rx-y    Display real storage locations x to y
vx      Display 64 bytes starting at virtual address x
vx.n    Display n bytes starting at virtual address x
vx-y    Display virtual storage locations x to y
f-x     Mark storage frame at address x unusable
f+x     Mark storage frame at address x usable
 
rx=hexvalue   Alter real storage location x
vx=hexvalue   Alter virtual storage location x
 
t+      Turn on CPU instruction tracing
t-      Turn off CPU instruction tracing
s+      Turn on CPU single-step mode
s-      Turn off CPU single-step mode
g       Go (turn off CPU single-step mode and start CPU)
 
bx      Set breakpoint at address x
b-      Clear breakpoint
 
t+xxxx  Turn on CCW tracing for device number xxxx
t-xxxx  Turn off CCW tracing for device number xxxx
s+xxxx  Turn on CCW single-step mode for device number xxxx
s-xxxx  Turn off CCW single-step mode for device number xxxx
ixxxx   Generate an I/O attention interrupt for device number xxxx
 
loadparm [xxxxxxxx]  Display or set the IPL parameter
loadcore xxxxxxxx    Load core image from file xxxxxxxx
ipl xxxx             IPL from device number xxxx
 
ext      Generate an external interrupt
stop     Stop CPU
start    Start CPU
stopall  Stop all CPUs
startall Start all CPUs
restart  Generate a restart interrupt and start CPU
store    Store status
quit     Terminate Hercules
 
devlist  Display configured devices
attach xxxx type [ args ]  Create device xxxx
detach xxxx  Delete device xxxx
define xxxx yyyy  Rename device number xxxx to yyyy
devinit xxxx [ args ]  Reinitialize device xxxx
 
.text   Enter an SCP command via the HMC system console
!text   Enter an SCP priority message via the HMC system console
 
toddrag [n]  Display or set TOD clock drag factor
 
pgmtrace n   Turn on program interrupt tracing for interrupt code n
pgmtrace -n  Turn off program interrupt tracing for interrupt code n
 
panrate slow | fast | n   Set panel refresh rate to n milliseconds

The attach and detach commands are used to dynamically add or remove devices from the configuration, and the define command can be used to alter the device number of an existing device.

The devinit command can be used to reopen an existing device. The args (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.

In single-step mode, pressing the enter key will advance to the next instruction.

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.

If you have a question about Hercules, see the Hercules Frequently-Asked Questions [ http://www.conmicro.cx/hercules/hercfaq.html ] page.

Last updated 18 January 2001