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/bldlvlck

  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 host's command prompt:

    hercules  [ -f filename ]
              [ -d ]
              [ -p dyndir ]  [[-l dynmod ] ... ]
              [ -s symbol=value ]
              [ > 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.

symbol=value

the name of symbol and the associated value to be used in configuration processing or panel commands. See the command 'defsym' for more information on using symbols. The '-s' option maybe repeated. Note: 'value' maybe quoted to contain imbedded blanks.

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
     -------      -----------------------------------------------
     !message     SCP priority messsage
     #            Silent comment
     *            Loud comment
     .reply       SCP command
     ?            alias for help
     aea          Display AEA tables
     aia          Display AIA fields
     alrf         Command deprecated: Use "archlvl enable|disable|query asn_lx_reuse" instead
     ar           Display access registers
     archlvl      Set Architecture Level
     archmode     Alias for archlvl
     asn_and_l    Command deprecated: Use "archlvl enable|disable|query asn_lx_reuse" instead
     attach       Configure device
     auto_scsi    Command deprecated - Use "SCSIMOUNT"
     autoinit     Display/Set automatic create empty tape file switch
     automount    Display/Update allowable tape automount directories
     b            Set breakpoint
     b+           Set breakpoint
     b-           Delete breakpoint
     cache        Execute cache related commands
     cachestat    Cache stats command
     capping      Set/display capping value
     cckd         cckd command
     cd           Change directory
     cf           Configure current CPU online or offline
     cfall        Configure all CPU's online or offline
     clocks       Display tod clkc and cpu timer
     cmdlevel     Display/Set current command group
     cmdlvl       (alias for cmdlevel)
     cmdsep       Display/Set command line separator
     cmdtgt       Specify the command target
     cnslport     Set console port
     codepage     Set/display code page conversion table
     conkpalv     Display/alter console TCP keep-alive settings
     cp_updt      Create/Modify user character conversion table
     cpu          Define target cpu for panel display and commands
     cpuidfmt     Set format 0/1 STIDP generation
     cpumodel     Set CPU model number
     cpuprio      Set/Display cpuprio parameter
     cpuserial    Set CPU serial number
     cpuverid     Set CPU verion number
     cr           Display or alter control registers
     cscript      Cancels a running script thread
     ctc          Enable/Disable CTC debugging
     define       Rename device
     defstore     Define/Display main and expanded storage values
     defsym       Define symbol
     delsym       Delete a symbol
     detach       Remove device
     devinit      Reinitialize device
     devlist      List device, device class, or all devices
     devprio      Set/Display devprio parameter
     devtmax      Display or set max device threads
     diag8cmd     Set diag8 command option
     dir          Displays a list of files and subdirs in a directory
     ds           Display subchannel
     ecps:vm      Command deprecated - Use "ECPSVM"
     ecpsvm       ECPS:VM Commands
     engines      Set engines parameter
     evm          Command deprecated - Use "ECPSVM"
     exit         (Synonym for 'quit')
     ext          Generate external interrupt
     fcb          Display the current FCB (if only the printer is given)
     fpc          Display floating point control register
     fpr          Display floating point registers
     f{+/-}adr    Mark frames unusable/usable
     g            Turn off instruction stepping and start all CPUs
     gpr          Display or alter general purpose registers
     hao          Hercules Automatic Operator
     help         list all commands / command specific help
     herc         Hercules command
     herclogo     Read a new hercules logo file
     hercprio     Set/Display hercprio parameter
     hst          History of commands
     http         Start/Stop/Modify/Display HTTP Server
     httpport     Command deprecated - Use "HTTP PORT ..."
     httproot     Command deprecated - Use "HTTP ROOT fn"
     i            Generate I/O attention interrupt for device
     iodelay      Display or set I/O delay value
     ipending     Display pending interrupts
     ipl          IPL Normal from device xxxx
     iplc         IPL Clear from device xxxx
     k            Display cckd internal trace
     kd           Short form of 'msghld clear'
     ldmod        Load a module
     legacysen    Set legacysenseid setting
     loadcore     Load a core image file
     loadparm     Set IPL parameter
     loadtext     Load a text deck file
     log          Direct logger output
     logopt       Set/Display logging options
     lparname     Set LPAR name
     lparnum      Set LPAR identification number
     lsdep        List module dependencies
     lsmod        List dynamic modules
     mainsize     Define/Display mainsize parameter
     manufactu    Set STSI manufacturer code
     maxcpu       Set maxcpu parameter
     maxrates     Display highest MIPS/SIOS rate or set interval
     message      Display message on console a la VM
     model        Set/Query STSI model code
     modpath      Set module load path
     mounted_t    Control tape initialization
     msg          Alias for message
     msghld       Display or set the timeout of held messages
     msglevel     Display/Set current Message Display output
     msglvl       Alias for msglevel
     msgnoh       Similar to "message" but no header
     mt           Control magnetic tape operation
     numcpu       Set numcpu parameter
     numvec       Set numvec parameter
     ostailor     Tailor trace information for specific OS
     panrate      Display or set rate at which console refreshes
     pantitle     Display or set console title
     pgmprdos     Set LPP license setting
     pgmtrace     Trace program interrupts
     plant        Set STSI plant code
     pr           Display prefix register
     pscp         Send prio message scp command
     psw          Display or alter program status word
     ptt          Set or display internal trace
     pwd          Print working directory
     qcpuid       Display cpuid
     qd           Query dasd
     qpfkeys      Display the current PF Key settings
     qpid         Display Process ID of Hercules
     qports       Display TCP/IP ports in use
     qproc        Display processors type and utilization
     qstor        Display main and expanded storage values
     quiet        Toggle automatic refresh of panel display data
     quit         Terminate the emulator
     r            Display or alter real storage
     restart      Generate restart interrupt
     resume       Resume hercules
     rmmod        Delete a module
     s            Instruction stepping
     s+           Instruction stepping on
     s-           Turn off instruction stepping
     s?           Instruction stepping query
     savecore     Save a core image to file
     sclproot     Set SCLP base directory
     scp          Send scp command
     scpecho      Set/Display option to echo to console and history of scp replys
     scpimply     Set/Display option to pass non-hercules commands to the scp
     script       Run a sequence of panel commands contained in a file
     scsimount    Automatic SCSI tape mounts
     sf+dev       Add shadow file
     sf-dev       Delete shadow file
     sfc          Compress shadow files
     sfd          Display shadow file stats
     sfk          Check shadow files
     sh           Shell command
     shcmdopt     Set diag8 sh option
     showdvol1    Enable showing of dasd volsers in device list
     shrd         shrd command
     shrdport     Set shrdport value
     sizeof       Display size of structures
     srvprio      Set/Display srvprio parameter
     ssd          Signal shutdown
     start        Start CPU (or printer/punch device if argument given)
     startall     Start all CPU's
     stop         Stop CPU (or printer/punch device if argument given)
     stopall      Stop all CPU's
     store        Store CPU status at absolute zero
     suspend      Suspend hercules
     symptom      Alias for traceopt
     syncio       Display syncio devices statistics
     sysclear     System Clear Reset manual operation
     sysepoch     Set sysepoch parameter
     sysreset     System Reset manual operation
     s{+/-}dev    Turn CCW stepping on/off
     t            Instruction trace
     t+           Instruction trace on
     t-           Turn off instruction tracing
     t?           Instruction trace query
     timerint     Display or set timers update interval
     tlb          Display TLB tables
     toddrag      Display or set TOD clock drag factor
     todprio      Set/Display todprio parameter
     traceopt     Instruction trace display options
     tt32         Control/query CTCI-W32 functionality
     tzoffset     Set tzoffset parameter
     t{+/-}CKD    Turn CKD_KEY tracing on/off
     t{+/-}dev    Turn CCW tracing on/off
     u            Disassemble storage
     uptime       Display how long Hercules has been running
     v            Display or alter virtual storage
     version      Display version information
     xpndsize     Define/Display xpndsize parameter
     yroffset     Set yroffset parameter

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)

When a command is prefixed with '-', the the command will not be redisplayed at the console. This can be used in scripts and is also used internally when commands are to be invoked without being redisplayed at the panel.


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.


The "Hercules Automatic Operator" (HAO) Facility

The Hercules Automatic Operator (HAO) feature is a facility that allows one to automatically issue panel commands in response to certain messages being issued.

To use the Hercules Automatic Operator facility, one first defines a "rule" consisting of a "target" and an associated "command". The "target" is just a regular expression pattern used to match against the text of the various messages that Hercules issues as it runs. Whenever a match is found, the rule "fires" and its associated command is automatically issued.

The Hercules Automatic Operator facility is only for those messages issued by Hercules to its HMC (hardware console). It cannot be used for whatever messages the guest operating system may issue to any of its terminals. It is only a Hercules automatic operator and not a "VSE", "MVS", "VM", etc, automatic operator.

Defining a Rule

To define a HAO rule, enter the command:

   hao target

to define the rule's "target" match pattern (a simple regular expression), followed by the command:

   hao command

to define the rule's associated panel-command.

The target pattern is a simple regular expression value as defined by whatever regular expression facility your host build platform happens to support. For Windows it must be a Perl Compatible Regular Expression (PCRE). For other supported build platforms it might be some other supported regular expression syntax. Check your host platform's programming documentation for further details.

The associated command is whatever valid Hercules panel command you wish to issue in response to a message being issued that matches the given pattern target.

Other commands and limitations

To delete a fully or partially defined HAO rule, first use the 'hao list' command to list all of the defined (or partially defined) rules, and then use the 'hao del nnn' command to delete the specific rule identified by nnn. (All rules are assigned numbers as they are defined and are thus identified by their numeric value). Optionally, one may delete ALL defined or partially defined rules by issuing the command 'hao clear'.

The current implementation limits the total number of defined rules to 64. If you need to define more than 64 rules you will either have to build Hercules for yourself (increasing the value of the HAO_MAXRULE constant in hao.c) or else beg one of the Hercules developers to please do it for you.

Note that there is currently no way to define a command whose arguments vary based on actual message text. That is to say, there is currently no way to say

"Reply with the command 'devinit cuu filename' in response to message text 'HHCXXnnnI Device cuu intervention required.' where cuu is whatever cuu was identified in the message."

The HAO is not that sophisticated (yet). Only simple plain-text commands may be defined and issued. No automatic substitution is done based on message text (although normal 'DEFSYM' symbol substitution is supported however, as that is a normal panel-command feature supported separately from the HAO). This may possibly change in the future however, depending on user need/demand.

All defined rules are checked for a match each time Hercules issues a message. There is no way to specify "stop processing subsequent rules". If a message is issued that matches two or more rules, each associated command is then issued in sequence. Thus the advice to choose your rules' target patterns carefully very much applies here.


Technical Support

For technical support, please see our Technical Support web page.


back

Last updated $Date: 2011-05-29 07:05:53 +0000 (Sun, 29 May 2011) $ $Revision: 7473 $