Hercules Version 3: Installation and Operation

Contents

Installation Procedure

Configuration Procedure

Creating DASD volumes

Operating Procedure

Technical Support

Installation Procedure

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 - 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 - Linux and Mac OS X

  1. Download the distribution file hercules-3.07.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.07.tar.gz
cd hercules-3.07
  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:
  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.

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.07-tiger.dmg, hercules-3.07-leopard.dmg, or hercules-3.07-snowleopard.dmg. This package is a universal binary and requires the OS X version in the name, either 10.4 (Tiger), 10.5 (Leopard), 10.6 (Snow Leopard) or later. The Leopard and Snow Leopard versions include native 64-bit host support, while the Tiger version does not. The Tiger and Leopard versions will run on Intel or PowerPC Macs, while the Snow Leopard version will only run on Intel, as with Snow Leopard itself.
  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.

Installing on Windows (without Cygwin):

  1. Download the Windows 32-bit Installer package or the Windows 64-bit Installer package.
  2. 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. Hercules 3.07 is now supplied as prebuilt binaries only in a native Windows version. This version will work perfectly well under Cygwin, as well as native Windows, and does not require any specific version of the Cygwin libraries. Follow the instructions above to install the native Windows version.

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.

Starting Hercules

To start Hercules enter this command at the Unix or Windows command prompt: 

    hercules  [ -f filename ]
              [ -d ]
              [ -p dyndir ]  [[-l dynmod ] ... ]
              [ > logfile ]

where:

filename

is the name of the configuration file. The default, if none is specified, is hercules.cnf. The default may be overridden via the HERCULES_CNF environment variable.

-d

specifies that Hercules is to be run in 'daemon' mode, wherein it runs invisibly with no attached console.

dyndir

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.

dynmod

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 -l option specifier.

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.


Using the keyboard

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.

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.

Important messages are highlighted in a different color (usually red) and are prevented from being scrolled off the screen for two minutes. If Extended Cursor handling is available then important messages currently at the top of the screen can be removed early by moving the cursor to the line containing the message and then pressing enter.

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.

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.

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.

Normal cursor handling
Key Action
Esc Erases the contents of the command input area. If the command input area is already empty, switches to semi-graphical New Panel.
Del Deletes the character at the cursor position.
Backspace Erases the previous character.
Insert Toggles between insert mode and overlay mode.
Tab 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.
Home 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.
End 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.
Page Up Scrolls the message area up one screen.
Page Down Scrolls the message area down one screen.
Up arrow Recalls previous command into the input area.
Down arrow Recalls next command into the input area.
Right arrow Moves cursor to next character of input area.
Left arrow Moves cursor to previous character of input area.
Ctrl + Up arrow Scrolls the message area up one line.
Ctrl + Down arrow Scrolls the message area down one line.
Ctrl + Home Scrolls the message area to the top.
Ctrl + End Scrolls the message area to the bottom.

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.

Extended cursor handling
Key Action
Alt + Up arrow Moves cursor up one row.
Alt + Down arrow Moves cursor down one row.
Alt + Right arrow Moves cursor right one column.
Alt + Left arrow Moves cursor left one column.
Tab 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.
Home 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.
End 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.

Panel commands

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. Please enter the '?' command for yourself for a more complete, accurate and up-to-date list of supported panel commands. 


  Command      Description... 
  -------      ----------------------------------------------- 
  ?            list all commands 
  help         command specific help
 
  *            (log comment to syslog)
 
  message      display message on console a la VM 
  msg          same as message 
  msgnoh       same as message - no header
 
  hst          history of commands 
  hao          Hercules Automatic Operator 
  log          direct log output 
  logopt       change log options 
  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 current 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 
  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 
  store        store CPU status at absolute zero
 
  psw          display or alter program status word 
  gpr          display or alter general purpose registers 
  fpr          display floating point registers 
  fpc          display floating point control register 
  cr           display or alter control registers 
  ar           display access registers 
  pr           display prefix register 
  timerint     display or set timers update interval 
  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 device or all devices
 
  qd           query dasd
 
  automount    show/update allowable tape automount directories
 
  scsimount    automatic SCSI tape mounts
 
  cd           change directory 
  pwd          print working directory 
  sh           shell command
 
  cache        cache command 
  cckd         cckd command 
  shrd         shrt working directory 
  sh           shell command
 
  cache        cache command 
  cckd         cckd command 
  shrd         shrt working directory 
  sh           shell command
 
  cache        cache command 
  cckd         cckd command 
  shrd         shrt working directory 
  sh           shell command
 
  cache        cache command 
  cckd         cckd command 
  shrd         shrt working directory 
  sh           shell command
 
  cache        cache command 
  cckd         cckd command 
  shrd         shrt working directory 
  sh           shell command
 
  cache        cache command 
  cckd         cckd command 
  shrd         shrt working directory 
  sh           shell command
 
  cache        cache command 
  cckd         cckd command 
  shrd         shrt working directory 
  sh           shell command
 
  cache        cache command 
  cckd         cckd command 
  shrd         shrt working directory 
  sh           shell command
 
  cache        cache command 
  cckd         cckd command 
  shrd         shrt working directory 
  sh           shell command
 
  cache        cache command 
  cckd         cckd command 
  shrd         shrt working directory 
  sh           shell command
 
  cache        cache command 
  cckd         cckd command 
  shrd         shrt working directory 
  sh           shell command
 
  cache        cache command 
  cckd         cckd command 
  shrd         shrt working directory 
  sh           shell command
 
  cache        cache command 
  cckd         cckd command 
  shrd         shrt working directory 
  sh           shell command
 
  cache        cache command 
  cckd         cckd command 
  shrd         shrt working directory 
  sh           shell command
 
  cache        cache command 
  cckd         cckd command 
  shrd         shrt working directory 
  sh           shell command
 
  cache        cache command 
  cckd         cckd command 
  shrd         shrt working directory 
  sh           shell command
 
  cache        cache command 
  cckd         cckd command 
  shrd         shrt working directory 
  sh           shell command
 
  cache        cache command 
  cckd         cckd command 
  shrd         shrt working directory 
  sh           shell command
 
  cache        cache command 
  cckd         cckd command 
  shrd         shrt working directory 
  sh           shell command
 
  cache        cache command 
  cckd         cckd command 
  shrd         shrt working directory 
  sh           shell command
 
  cache        cache command 
  cckd         cckd command 
  shrd         shrt working directory 
  sh           shell command
 
  cache        cache command 
  cckd         cckd command 
  shrd         shrt working directory 
  sh           shell command
 
  cache        cache command 
  cckd         cckd command 
  shrd         shrt working directory 
  sh           shell command
 
  cache        cache command 
  cckd         cckd command 
  shrd         shrt working directory 
  sh           shell command
 
  cache        cache command 
  cckd         cckd command 
  shrd         shrt working directory 
  sh           shell command
 
  cache        cache command 
  cckd         cckd command 
  shrd         shrt working directory 
  sh           shell command
 
  cache        cache command 
  cckd         cckd command 
  shrd         shrt working directory 
  sh           shell command
 
  cache        cache command 
  cckd         cckd command 
  shrd         shrt working directory 
  sh           shell command
 
  cache        cache command 
  cckd         cckd command 
  shrd         shrt working directory 
  sh           shell command
 
  cache        cache command 
  cckd         cckd command 
  shrd         shrt working directory 
  sh           shell command
 
  cache        cache command 
  cckd         cckd command 
  shrd         shrt working directory 
  sh           shell command
 
  cache        cache command 
  cckd         cckd command 
  shrd         shrt working directory 
  sh           shell command
 
  cache        cache command 
  cckd         cckd command 
  shrd         shrt working directory 
  sh           shell command
 
  cache        cache command 
  cckd         cckd command 
  shrd         shrt working directory 
  sh           shell command
 
  cache        cache command 
  cckd         cckd command 
  shrd         shrt working directory 
  sh           shell command
 
  cache        cache command 
  cckd         cckd command 
  shrd         shrt working directory 
  sh           shell command
 
  cache        cache command 
  cckd         cckd command 
  shrd         shrt working directory 
  sh           shell command
 
  cache        cache command 
  cckd         cckd command 
  shrd         shrt working directory 
  sh           shell command
 
  cache        cache command 
  cckd         cckd command 
  shrd         shrt working directory 
  sh           shell command
 
  cache        cache command 
  cckd         cckd command 
  shrd         shrt working directory 
  sh           shell command
 
  cache        cache command 
  cckd         cckd command 
  shrd         shrt working directory 
  sh           shell command
 
  cache        cache command 
  cckd         cckd command 
  shrd         shrt working directory 
  sh           shell command
 
  cache        cache command 
  cckd         cckd command 
  shrd         shrt working directory 
  sh           shell command
 
  cache        cache command 
  cckd         cckd command 
  shrd         shrt working directory 
  sh           shell command
 
  cache        cache command 
  cckd         cckd command 
  shrd         shrt working directory 
  sh           shell command
 
  cache        cache command 
  cckd         cckd command 
  shrd         shrt working directory 
  sh           shell command
 
  cache        cache command 
  cckd         cckd command 
  shrd         shrt working directory 
  sh           shell command
 
  cache        cache command 
  cckd         cckd command 
  shrd         shrt working directory 
  sh           shell command
 
  cache        cache command 
  cckd         cckd command 
  shrd         shrt working directory 
  sh           shell command
 
  cache        cache command 
  cckd         cckd command 
  shrd         shrt working directory 
  sh           shell command
 
  cache        cache command 
  cckd         cckd command 
  shrd         shrt working directory 
  sh           shell command
 
  cache        cache command 
  cckd         cckd command 
  shrd         shrt working directory 
  sh           shell command
 
  cache        cache command 
  cckd         cckd command 
  shrd         shrt working directory 
  sh           shell command
 
  cache        cache command 
  cckd         cckd command 
  shrd         shrt working directory 
  sh           shell command
 
  cache        cache command 
  cckd         cckd command 
  shrd         shrt working directory 
  sh           shell command
 
  cache        cache command 
  cckd         cckd command 
  shrd         shrt working directory 
  sh           shell command
 
  cache        cache command 
  cckd         cckd command 
  shrd         shrt working directory 
  sh           shell command
 
  cache        cache command 
  cckd         cckd command 
  shrd         shrt working directory 
  sh           shell command
 
  cache        cache command 
  cckd         cckd command 
  shrd         shrt working directory 
  sh           shell command
 
  cache        cache command 
  cckd         cckd command 
  shrd         shrt working directory 
  sh           shell command
 
  cache        cache command 
  cckd         cckd command 
  shrd         shrt working directory 
  sh           shell command
 
  cache        cache command 
  cckd         cckd command 
  shrd         shrt working directory 
  sh           shell command
 
  cache        cache command 
  cckd         cckd command 
  shrd         shrt working directory 
  sh           shell command
 
  cache        cache command 
  cckd         cckd command 
  shrd         shrt working directory 
  sh           shell command
 
  cache        cache command 
  cckd         cckd command 
  shrd         shrt working directory 
  sh           shell command
 
  cache        cache command 
  cckd         cckd command 
  shrd         shrt working directory 
  sh           shell command
 
  cache        cache command 
  cckd         cckd command 
  shrd         shrt working directory 
  sh           shell command
 
  cache        cache command 
  cckd         cckd command 
  shrd         shrt working directory 
  sh           shell command
 
  cache        cache command 
  cckd         cckd command 
  shrd         shrt working directory 
  sh           shell command
 
  cache        cache command 
  cckd         cckd command 
  shrd         shrt working directory 
  sh           shell command
 
  cache        cache command 
  cckd         cckd command 
  shrd         shrt working directory 
  sh           shell command
 
  cache        cache command 
  cckd         cckd command 
  shrd         shrt working directory 
  sh           shell command
 
  cache        cache command 
  cckd         cckd command 
  shrd         shrt working directory 
  sh           shell command
 
  cache        cache command 
  cckd         cckd command 
  shrd         shrt working directory 
  sh           shell command
 
  cache        cache command 
  cckd         cckd command 
  shrd         shrt working directory 
  sh           shell command
 
  cache        cache command 
  cckd         cckd command 
  shrd         shrt working directory 
  sh           shell command
 
  cache        cache command 
  cckd         cckd command 
  shrd         shrt working directory 
  sh           shell command
 
  cache        cache command 
  cckd         cckd command 
  shrd         shrt working directory 
  sh