Hercules Version 2: Installation and Operation

# Installing and Operating Hercules Version 2

## 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.

1. Download the distribution file hercules-2.15.tar.gz

   Notes:

   1. By downloading this file you agree to the terms of the Q Public Licence.
   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.

2. Use these commands to unzip the distribution file:

       tar xvzf ../hercules-2.15.tar.gz
       cd hercules-2.15

3. Configure Hercules for your system:

   `./configure`

   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 disable all optimization by passing the `--disable-optimization` option to configure, or specify your own optimization flags with `--enable-optimization=FLAGS`

   For additional configuration options, run `./configure --help`

4. Build the executables:

   `make`

5. 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 page for required compiler and other software levels.

### Installing prebuilt RPMs:

1. Download the RPM file you want:
   - hercules-2.15-1.i686.rpm: Intel Pentium Pro/Pentium II
   - hercules-2.15-1.i586.rpm: Intel Pentium
   - hercules-2.15-1.i386.rpm: Intel 386
   - hercules-2.15-1.alpha.rpm: Alpha (all flavors)
2. 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.

### Installing Debian packages:

Debian packages are available for "woody" and later releases. As of this writing, "woody" is not yet released.

- Using apt: `apt-get install hercules`
- Manually with dpkg:
  1. Download a .deb package
  2. `dpkg -i` DEB

## Configuration Procedure

You will need to amend the configuration file hercules.cnf to reflect your device layout and intended mode of operation (S/370, ESA/390, or z/Architecture). See the Hercules Configuration File page for a complete description.

## Creating DASD volumes

The Creating Hercules DASD page describes various methods of creating and loading virtual DASD volumes. The compressed CKD DASD support is described in this page.

## 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 enter this command at the Unix shell prompt:

    hercules [-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
    clocks  Display todclock, clock comparator, cpu timer, and interval timer (370 mode only)

    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+ckd            Turn on CKD key tracing
    t-ckd            Turn off CKD key tracing
    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
    kxxxx   Print CCKD internal trace for device number xxxx
    dsxxxx  Display subchannel status for device number xxxx

    archmode S/370|ESA/390|ESAME  Set architecture mode
    loadparm [xxxxxxxx]           Display or set the IPL parameter
    loadcore xxxxxxxx [address]   Load core image from file xxxxxxxx
    savecore xxxxxxxx [start/*] [end/*] save core to file xxxxxxxx
    loadtext xxxxxxxx [address]   Load object deck 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
    ipending  Display pending interrupts
    quit|exit Terminate Hercules
    quiet     Toggles panel quiet mode

    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 ipl 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: ipl /cdrom/suse.ins

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 page.

Last updated 02 December 2001