# Hercules Version 3: Installation and Operation

## Contents

> Installation Procedure

> - - Building from source
> - - Pre-built binaries

> Configuration Procedure

> Creating DASD volumes

> Operating Procedure

> .RC ("run commands") file

> Technical Support

## Installation Procedure

### Building from source - Windows with Cygwin

For building the Cygwin version of Hercules on Windows, Volker Bandke has instructions on his "Building Hercules for Windows" web page at http://www.bsp-gmbh.com/hercules/herc_w32_2.html.

### Building from source - Windows (without Cygwin)

For building the MSVC version of Hercules on Windows (a version of Hercules that does not require Cygwin), Fish has instructions on his "MSVC Hercules Build Instructions" web page at http://www.softdevlabs.com/Hercules/hercules-msvc-build.html.

### Building from source - Linux and Mac OS X

1. Download the distribution file hercules-3.03.1.tar.gz
   Note: By downloading this file you agree to the terms of the Q Public Licence.

2. Use these commands to unzip the distribution file:

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

3. Verify you have all of the correct versions of all of the required packages installed:

   `./util/cvslvlck`

4. 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`

5. Build the executables:

   `make`

6. Install the programs: as root:

   `make install`

Important: You must use at least version 2.95 of the gcc 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-3.03.1-1.i686.rpm: Intel
2. Install the RPM:
   `rpm -Uvh` RPMfile

This will leave the Hercules executables in /usr/bin and the dynamic libraries in /usr/lib and /usr/lib/hercules, 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.

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

### Installing on Gentoo Linux:

Hercules is installed like any other Gentoo package: do `emerge sync` if you haven't done it lately, then `emerge hercules`.

Do not try to override the optimization flags automatically selected by `configure`. Hercules stresses the gcc optimizer, and will break in subtle ways if the wrong optimization settings are used.

### Installing on Mac OS X:

1. Download the compressed disk image: hercules-3.03.1-panther.dmg if you're running OS X version 10.3, or hercules-3.03.1-tiger.dmg if you're running version 10.4 or later.
2. Mount the image by double-clicking on it in the Finder. Your web browser may have done that for you already.
3. Installation and use instructions are in the file `OS X ReadMe.rtf`.
4. If you want to use CTC networking on your Hercules system, you will need to install the supplied Tunnel driver. Note that, at this writing, the Panther version of the driver works fine, but the Tiger version will hang at Hercules shutdown, and you must reboot in order to clear the problem. Unfortunately, the Panther driver will not work on Tiger at all.

### Installing on Windows (without Cygwin):

1. Download the self-extracting Windows archive or the Windows Installer package.
2. If you downloaded the self-extracting archive, simply execute it to install Hercules on your system. If you downloaded the Windows Installer package, use the Windows Installer to install Hercules. The Windows Installer is included in Windows XP. It may already be on your older Windows system, depending on what other software you've installed. If it is, double-clicking on the Hercules package file will install Hercules. If not, you can download the Windows Installer for Windows NT and 2000 by following this link, or the Windows Installer for Windows 98 and ME by following this link.
3. You will probably also want to install Fish's Hercules GUI for Windows. You can get it from http://www.softdevlabs.com/Hercules/hercgui-index.html.

### Installing on Windows with Cygwin:

1. You must first install the Cygwin package. Download the 'setup.exe' program from the Cygwin site, and run it. (Right-click on the icon labeled "Install or update now! (using setup.exe)" and select "Save Target As..." and then run it after it's been downloaded) If it's not preselected for you, select the libintl-2 package when you're presented with a list of packages to install. (NOTE: Hercules version 3.03.1 was built with version 1.5.15 of Cygwin, and may not work with other versions, as the Cygwin library tends to have subtle incompatibilities from version to version that Hercules seems to stress.)
2. Download the self-extracting Windows archive:
   - hercules-3.03.1-cygwin-p4.exe: Pentium 4 version
   - hercules-3.03.1-cygwin-i686.exe: Pentium Pro/Pentium II and above version
   - hercules-3.03.1-cygwin-i586.exe: Pentium version
3. Run one of the above self-extracting archives to install the Hercules executables on your system. Also please note that Hercules has several file paths compiled into the code, and so it is best to install the package into the default directories unless you really know what you're doing.

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

        Command      Description...
        -------      -----------------------------------------------
        ?            list all commands
        help         command specific help

        *            (log comment to syslog)

        hst          history of commands
        log          direct log output
        version      display version information

        quit         terminate the emulator
        exit         (synonym for 'quit')

        cpu          define target cpu for panel display and commands

        start        start CPU (or printer device if argument given)
        stop         stop CPU (or printer device if argument given)

        startall     start all CPU's
        stopall      stop all CPU's

        cf           configure CPU online or offline
        cfall        configure all CPU's online or offline

        .reply       scp command
        !message     scp priority messsage
        ssd          Signal Shutdown

        ptt          display pthread trace

        i            generate I/O attention interrupt for device
        ext          generate external interrupt
        restart      generate restart interrupt
        store        store CPU status at absolute zero
        archmode     set architecture mode
        loadparm     set IPL parameter

        ipl          IPL Normal from device xxxx
        iplc         IPL Clear from device xxxx
        sysreset     Issue SYSTEM Reset manual operation
        sysclear     Issue SYSTEM Clear Reset manual operation

        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 tod clkc and cpu timer
        ipending     display pending interrupts
        ds           display subchannel
        r            display or alter real storage
        v            display or alter virtual storage
        u            disassemble storage
        devtmax      display or set max device threads
        k            display cckd internal trace

        attach       configure device
        detach       remove device
        define       rename device
        devinit      reinitialize device
        devlist      list all devices

        scsimount    automatic SCSI tape mounts

        sh           shell command
        cache        cache command
        cckd         cckd command
        shrd         shrd command
        quiet        toggle automatic refresh of panel display data

        b            set breakpoint
        b-           delete breakpoint
        g            turn off instruction stepping and start CPU

        ostailor     trace program interrupts
        pgmtrace     trace program interrupts
        savecore     save a core image to file
        loadcore     load a core image file
        loadtext     load a text deck file

        ldmod        load a module
        rmmod        delete a module
        lsmod        list dynamic modules
        lsdep        list module dependencies

        iodelay      display or set I/O delay value
        tt32stats    display CTCI-W32 statistics
        toddrag      display or set TOD clock drag factor
        panrate      display or set rate at which console refreshes
        syncio       display syncio devices statistics
        maxrates     display maximum observed MIPS/SIOS rate for the
                     defined interval or define a new reporting interval

        script       Run a sequence of panel commands contained in a file
        cscript      Cancels a running script thread

        evm          ECPS:VM Commands (Deprecated)
        ecpsvm       ECPS:VM Commands

        aea          Display AEA tables
        aia          Display AIA fields
        tlb          Display TLB tables

        sizeof       Display size of structures

        suspend      Suspend hercules
        resume       Resume hercules

        sf+          add shadow file
        sf-          delete shadow file
        sf=          rename shadow file
        sfc          compress shadow files
        sfd          display shadow file stats

        t{+/-}       turn instruction tracing on/off
        s{+/-}       turn instruction stepping on/off
        t{+/-}dev    turn CCW tracing on/off
        s{+/-}dev    turn CCW stepping on/off
        t{+/-}CKD    turn CKD_KEY tracing on/off
        f{+/-}adr    mark frames unusable/usable

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.

Some commands also offer additional help information regarding their syntax, etc. Enter "`help <command name>`" to display this additional help information. (Note: not every command supports help)

#### The hercules.rc (run-commands) file

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.

The default filename for the run-commands file is "hercules.rc", but may be overridden by setting the "`HERCULES_RC`" environment variable to the desired filename.

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.

Lines starting with '`#`' are treated as "silent comments" and are thus not logged to the console. Line starting with '`*`' however are treated as "loud comments" and will be logged.

In addition to being able to execute any valid panel command (including the 'sh' shell command) via the run-commands file, an additional '`pause nnn`' command is supported in order to introduce a brief delay before reading and processing the next line in the file. The value `nnn` can be any number from 1 to 999 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.

## Technical Support

Please see our Technical Support web page.

Last updated $Date: 2005/12/29 10:38:33 $ $Revision: 1.39 $