This page describes the configuration file for the Hercules S/370, ESA/390, and z/Architecture emulator.
The configuration file hercules.cnf contains the processor and device layout. It is roughly equivalent to the IOCDS on a real System/390. The configuration file is an ASCII text file.
|
Blank lines, and lines beginning with a # sign or an asterisk, are treated as comments.
System parameters may appear in any order but they must precede all device records. Each system parameter must be on a separate line. The following system parameters may be specified:
ASN_AND_LX_REUSE DISABLE | ENABLE
specifies that the ASN-and-LX-Reuse Facility (ALRF) is to be disabled
or enabled. The default is disabled. This is a z/Architecture-only
feature (it is always disabled for S/390 or ESA/390). Set this
to ENABLE if the operating system supports
this z/Architecture feature and the use of this feature is desired.
Set it to DISABLE or do not specify anything
if the operating system doesn't support this feature, and it
inadvertently sets CR0 bit 44 to 1, usually leading to unexpected
program interrupt when instructions such as LASP are issued.
ASN_AND_LX_REUSE may be abbreviated as ALRF
AUTO_SCSI_MOUNT NO | nn
specifies whether automatic detection of SCSI tape mounts are to be enabled or not.
A value from 1 to 99 seconds inclusive enables the option and causes periodic queries of the SCSI tape drive to automatically detect when a new tape is mounted.
NO (the default) indicates the option is disabled, forcing all SCSI
tape mounts to be done manually via an appropriate devinit
command.
The scsimount panel command may also be used to display
and/or modify this value on demand once Hercules has been started. Note
too that the scsimount panel command also lists any mounts
and/or dismounts that may still be pending.
Note: enabling this option may negatively impact Hercules performance depending on how the host operating system (Windows, Linux, etc) handles SCSI attached tape drive status queries.
CPUSERIAL xxxxxx
specifies the 6 hexadecimal digit CPU serial number stored by the STIDP instruction
CPUMODEL xxxx
specifies the 4 hexadecimal digit CPU model number stored by the STIDP instruction
CPUVERID xx
specifies the 2 hexadecimal digit CPU version code stored by the STIDP instruction. The default version code is FD when ARCHMODE S/370 or ARCHMODE ESA/390 is specified. For the z/Architecture mode, 00 is used as default.
DEFSYM symbol value
Defines symbol symbol as to contain value value. The
symbol can then be the object of a substitution later in the configuration
file or for panel commands. If value contains blanks or spaces, then
it should be enclosed in double quotation marks ("). See
substitutions for a more in-depth discussion
on this feature. Substitution is available even in configuration statements,
meaning it is possible to perform substitution in the DEFSYM statement itself.
However, symbols are always defined as the last step in the process, so attempting
to self define a symbol will result in an empty string:
DEFSYM FOO $(FOO)
Will set symbol FOO to ""
LPARNAME name
specifies the LPAR name returned by DIAG X'204'. The default is
HERCULES.
MAINSIZE nnnn
specifies the main storage size in megabytes, where
nnnn is a decimal number. The lower limit is 2.
The actual upper limit is determined by your host system's architecture
and operating system, and (on some systems) the amount of physical
memory and paging space you have available.
XPNDSIZE nnnn
specifies the expanded storage size in megabytes, where
nnnn is a decimal number. The lower limit is 0.
The actual upper limit is determined by your host system's architecture
and operating system, and (on some systems) the amount of physical
memory and paging space you have available.
HTTPROOT directory
specifies the root directory where the HTTP server's files reside. If not specified, the default value for Win32 builds of Hercules is the directory where the Hercules executable itself is executing out of, and for non-Win32 builds it is the directory specified as the default package installation directory when the Hercules executable was built (which can vary depending on how the Hercules package was built, but is usually /usr/local/share/hercules/).
Note: Windows users of Hercules who do not have the complete Cygwin package installed (i.e. only have the required Cygwin DLLs installed instead) should specify this value in the form: "/cygdrive/x/pathname/" where 'x' is the Windows drive letter. For example, if the Windows directory where the http server's files reside is "K:\Hercules\html\", then you should specify "/cygdrive/k/Hercules/html/" on your HTTPROOT statement.
HTTPPORT nnnn [AUTH | NOAUTH] [ userid password ]
specifies the port number (in decimal) on which the HTTP server
will listen. The port number must either be 80
or within the range 1024 - 65535 inclusive. If no HTTPPORT statement is
present or an invalid port number is specified, then the HTTP server thread
will not be activated.
AUTH indictates that a userid and password are required to access
the HTTP server, whereas NOAUTH indicates that a userid and password
are not required. The userid and password may be any valid string.
SHRDPORT nnnn
specifies the port number (in decimal) on which the Shared Device server
will listen. Specifying SHRDPORT will allow other Hercules instances
to access devices on this instance. (Currently only DASD devices may
be shared). By default, the other Hercules instances (clients) will
use port 3990. If you specify a different port number, then you will
have to specify this port number on the device statement for the other
Hercules clients.
If no SHRDPORT statement is present then the Shared Device server thread
will not be activated.
DIAG8CMD DISABLE | ENABLE
When set to ENABLE, commands issued through diagnose 8 will be
executed by hercules as hercules commands. When set to DISABLE,
commands issued through the diagnose 8 interface will be ignored.
The default is DISABLE
Caution: Enabling this feature may have security consequences
Note that when this feature is enabled, systems
running under hercules can even issue host commands through the Hercules
sh (shell) command. This ability may be disabled via the
SHCMDOPT statement.
SHCMDOPT DISABLE | NODIAG8
When set to DISABLE, sh (shell) commands are globally disabled, and will result
in an error if entered either directly via the Hercules hardware console or
programmatically via the DIAG8CMD interface.
When set to NODIAG8 only the programmatic execution of shell commands via the
the diagnose 8 interface is disabled; sh (shell) commands entered directly
via the Hercules hardware console will still work.
NOTE: "entered directly via the Hercules hardware console" also pertains to both commands entered via the HTTP server facility as well as commands entered via .rc "run command" scripts.
CNSLPORT nnnn
specifies the port number (in decimal) to which tn3270 and telnet clients will connect
The CNSLPORT statement may also have the form of host:port, where the telnet console server will bind to the specified address.
NUMCPU nn
specifies the number of emulated CPUs.
Note:
Multiprocessor emulation is only available when the definition of
the compile-time variable MAX_CPU_ENGINES
in the file config.h has a value of more than 1.
Current versions of Hercules already have this value
set to 2 by default, so all you need to do is specify
NUMCPU 2
in your configuration file. If you wish to define a greater value
for MAX_CPU_ENGINES, use the
--enable-multi-cpu=NUMBER
option when you do your ./configure before doing your
make.
Multiprocessor emulation works best if your host system actually has more than one physical CPU, but you can still emulate multiple CPUs nervertheless even on a uniprocessor system (and you might even achieve a small performance benefit when you do). There is little point, however, in specifying NUMCPU greater than 1 unless your guest operating system (running under Hercules) is actually able to support multiple CPUs (and if you do not actually need multiprocessor emulation, then setting MAX_CPU_ENGINES to 1 at compile time might even produce a slight performance advantage too).
NUMVEC nn
specifies the number of emulated vector facilities. Default is one per CPU. Only available by default in ESA/390 mode.
HERCPRIO nn
specifies the process priority for Hercules. The default is 0. See "Process Priorities" below for more information.
CPUPRIO nn
specifies the priority of the CPU thread. Default is a nice value of 15, which means a low priority such that I/O can be scheduled and completed in favour of CPU cycles being burned. On Multi-CPU systems, a real CPU can be "dedicated" to Hercules, by giving the CPU thread a very high dispatching priority (-20). See "Thread Priorities" below for more information.
Caution: CPUPRIO should not have a higher dispatching priority than the TOD Clock and timer thread.
DEVPRIO nn
specifies the priority of the device threads. The default value is 8. See "Thread Priorities" below for more information.
Caution: DEVPRIO should not have a higher dispatching priority than the TOD Clock and timer thread.
TODPRIO nn
specifies the priority of the TOD Clock and timer thread. The default value is -20. See "Thread Priorities" below for more information.
Caution: TODPRIO should be given a dispatching priority equal to or higher than any other thread within Hercules.
LOADPARM xxxxxxxx
specifies the eight-character IPL parameter which is used by some operating systems to select system parameters
SYSEPOCH yyyy
specifies the base date for the TOD clock. Use the default
value (1900) for all systems except OS/360.
OS/360 expects the base date to be 1960, but specifying this
value causes an error because OS/360 regards 2000 as an invalid
date. For OS/360, SYSEPOCH 1988 is recommended.
This makes the year 2000 appear to be 1972.
TZOFFSET ±hhmm
specifies the hours and minutes by which the TOD clock will
be offset from the current system time. For GMT, use the
default value (0000). For timezones west of Greenwich, specify
a negative value (example: -0500 for US Eastern Standard
Time, -0800 for US Pacific Standard Time).
For timezones east of Greenwich, specify a positive value
(example: +0100 for Central European Time,
+0930 for South Australian Time).
TODDRAG nn
specifies the TOD clock drag factor. This parameter can be used to slow down or speedup the TOD clock by a factor of nn, a significant slowdown can improve the performance of some operating systems which consume significant amounts of CPU time processing timer interrupts. A drag factor of 2.0 slows down the clock by 50%, A drag factor of 0.5 doubles the speed of the clock, a drag factor of 1.01 slows down the clock by 1% and 0.99 speeds up the clock by 1%.
OSTAILOR OS/390 | z/OS |
VM | VSE | LINUX | QUIET | NULL
specifies the intended operating system. The effect of this
parameter is to reduce control panel message traffic by
selectively suppressing trace messages for program checks
which are considered normal in the specified environment.
QUIET discards all exception messages.
NULL allows all exception messages to be logged.
If this statement is omitted, exception messages for program
checks 10, 11, 16, and 1C are suppressed.
PANRATE SLOW | FAST | nn
specifies the panel refresh rate, in milliseconds between refreshes. SLOW is the same as 500, and FAST is the same as 50. A value less than the Linux system clock tick interval (10 on Intel, 1 on Alpha), or more than 5000, will be rejected. SLOW is the default.
ARCHMODE S/370 | ESA/390 | z/Arch | ESAME
specifies the initial architecture mode:
S/370 for OS/360, VM/370, and MVS 3.8.
ESA/390 for MVS/XA, MVS/ESA, OS/390, VM/ESA, VSE/ESA,
Linux/390, and ZZSA.
z/Arch or ESAME for z/OS and zLinux.
ESAME is a synonym for z/Arch.
When z/Arch or ESAME is specified,
the machine will always IPL in ESA/390 mode,
but is capable of being switched into z/Architecture mode after IPL.
This is handled automatically by all z/Architecture operating systems.
DEVTMAX -1 | 0 | nnn
specifies the maximum number of device threads allowed.
Specify -1 to cause 'one time only' temporary threads to be
created to service each I/O request to a device. Once the I/O request is
complete, the thread exits. Subsequent I/O to the same device will cause
another worker thread to be created again.
Specify 0 to cause an unlimited number of 'semi-permanent'
threads to be created on an 'as-needed' basis. With this option, a thread
is created to service an I/O request for a device if one doesn't already
exist, but once the I/O is complete, the thread enters an idle state waiting
for new work. If a new I/O request for the device arrives before the timeout
period expires, the existing thread will be reused. The timeout value is
currently hard coded at 5 minutes. Note that this option can cause one thread
(or possibly more) to be created for each device defined in your
configuration. Specifying 0 means there is no limit to the
number of threads that can be created.
Specify a value from 1 to nnn to set an upper limit
to the number of threads that can be created to service any I/O request to
any device. Like the 0 option, each thread, once done servicing
an I/O request, enters an idle state. If a new request arrives before the
timeout period expires, the thread is reused. If all threads are busy when
a new I/O request arrives however, a new thread is created only if the
specified maximum has not yet been reached. If the specified maximum number
of threads has already been reached, then the I/O request is placed in a queue
and will be serviced by the first available thread (i.e. by whichever thread
becomes idle first). This option was created to address a threading issue
(possibly related to the cygwin Pthreads implementation) on Windows systems.
The default for Windows is 8. The default for all other systems
is 0.
PGMPRDOS RESTRICTED | LICENSED
specifies whether or not Hercules will run licensed program product ESA
or z/Architecture operating systems. Specify RESTRICTED to
make Hercules emulate an IFL (Integrated Facility for Linux) CPU. With
this specified, licensed ESA or z/Architecture OSes will refuse to
start. OS/390 and z/OS will enter an A7A wait state, with reason code 7,
at IPL time. Specify LICENSED to allow these operating
systems to run normally. This parameter has no effect on Linux/390,
Linux for z/Series, or any 370-mode OS.
NOTE: It is YOUR responsibility to comply with the terms of the license for the operating system you intend to run on Hercules. If you specify LICENSED and run a licensed operating system in violation of that license, then don't come after the Hercules developers when the vendor sends his lawyers after you.
RESTRICTED is the default. Specifying
LICENSED will produce a message at Hercules startup to
remind you of your responsibility to comply with software license terms.
IODELAY usec [NOWARN]
specifies the amount of time (in microseconds) to wait after
an I/O interrupt is ready to be set pending. This value can also be
set using the Hercules console. The purpose of this parameter is to
bypass a bug in the Linux/390 and zLinux dasd.c
device driver. The problem is more apt to happen under Hercules than
on a real machine because we may present an I/O interrupt sooner than a
real machine.
If the IODELAY value is non-zero a warning message (HHCCF037W) will be
issued unless NOWARN is specified.
NOTE : OSTAILOR LINUX no longer sets
IODELAY to 800 since the problem described above is no longer present in
recent versions of the linux kernel.
CODEPAGE codepage
specifies the codepage conversion table used for ASCII/EBCDIC translation.
"default" specifies traditional hercules codepage. Code pages "437/037", "437/500" and "850/273" are also supported.
Iconv single byte codepages may also be used. (eg."UTF8/EBCDIC-CP-NL")
If no codepage is specified then the environment variable HERCULES_CP will be inspected. The default codepage used is "default"
he default codepage used is "default"
he default codepage used is "default"
he default codepage used is "default"
he default codepage used is "default"
he default codepage used is "default"
he default codepage used is "default"
he default codepage used is "default"
he default codepage used is "default"
he default codepage used is "default"
he default codepage used is "default"
he default codepage used is "default"
he default codepage used is "default"
he default codepage used is "default"
he default codepage used is "default"
he default codepage used is "default"
he default codepage used is "default"
he default codepage used is "default"
he default codepage used is "default"
he default codepage used is "default"
he default codepage used is "default"
he default codepage used is "default"
he default codepage used is "default"
he default codepage used is "default"
he default codepage used is "default"
he default codepage used is "default"
he default codepage used is "default"
he default codepage used is "default"
he default codepage used is "default"
he default codepage used is "default"
he default codepage used is "default"
he default codepage used is "default"
he default codepage used is "default"
he default codepage used is "default"
he default codepage used is "default"
he default codepage used is "default"
he default codepage used is "default"
he default codepage used is "default"
he default codepage used is "default"
he default codepage used is "default"
he default codepage used is "default"
he default codepage used is "default"
he default codepage used is "default"
he default codepage used is "default"
he default codepage used is "default"
he default codepage used is "default"
he default codepage used is "default"
he default codepage used is "default"
he default codepage used is "default"
he default codepage used is "default"
he default codepage used is "default"
he default codepage used is "default"
he default codepage used is "default"
he default codepage used is "default"
he default codepage used is "default"
he default codepage used is "default"
he default codepage used is "default"
he default codepage used is "default"
he default codepage used is "default"
he default codepage used is "default"
he default codepage used is "default"
he default codepage used is "default"
he default codepage used is "default"
he default codepage used is "default"
he default codepage used is "default"
he default codepage used is "default"
he default codepage used is "default"
he default codepage used is "default"
he default codepage used is "default"
he default codepage used is "default"
he default codepage used is "default"
he default codepage used is "default"
he default codepage used is "default"
he default codepage used is "default"
he default codepage used is "default"
he default codepage used is "default"
he default codepage used is "default"
he default codepage used is "default"
he default codepage used is "default"
he default codepage used is "default"
he default codepage used is "default"
he default codepage used is "default"
he default codepage used is "default"
he default codepage used is "default"
he default codepage used is "default"
he default codepage used is "default"
he default codepage used is "default"
he default codepage used is "default"
he default codepage used is "default"
he default codepage used is "default"
he default codepage used is "default"
he default codepage used is "default"
he default codepage used is "default"
he default codepage used is "default"
he default codepage used is "default"
he default codepage used is "default"
he default codepage used is "default"
he default codepage used is "default"
he default codepage used is "default"
he default codepage used is "default"
he default codepage used is "default"
he default codepage used is "default"
he default codepage used is "default"
he default codepage used is "default"
he default codepage used is "default"
he default codepage used is "default"
he default codepage used is "default"
he default codepage used is "default"
he default codepage used is "default"
he default codepage used is "default"
he default codepage used is "default"
he default codepage used is "default"
he default codepage used is "default"
he default codepage used is "default"
he default codepage used is "default"
he default codepage used is "default"
he default codepage used is "default"
he default codepage used is "default"
he default codepage used is "default"
he default codepage used is "default"
he default codepage used is "default"
he default codepage used is "default"
he default codepage used is "default"
he default codepage used is "default"
he default codepage used is "default"