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.
# # System parameters # CPUSERIAL 000611 CPUMODEL 3090 MAINSIZE 64 XPNDSIZE 0 CNSLPORT 3270 HTTPPORT 8081 NUMCPU 1 NUMVEC 1 CPUPRIO 15 ARCHMODE ESA/390 LOADPARM 0120.... SYSEPOCH 1900 TZOFFSET -0500 OSTAILOR OS/390 PANRATE FAST # # Device definitions # 000A 1442 adrdmprs.rdr 000C 3505 jcl.txt ascii trunc 000D 3525 pch00d.txt ascii 000E 1403 prt00e.txt 001F 3270 0120 3380 mvsv5r.120 0121 3380 mvsv5d.121 0122 3380 mvswk1.122 0140 3370 dosres.140 0141 3370 syswk1.141 0200 3270 0201 3270 0202 3270 0300 3370 sysres.300 0400 3088 CTCI /dev/tun0 1500 192.168.200.1 192.168.200.2 255.255.255.0 0401 3088 CTCI /dev/tun0 1500 192.168.200.1 192.168.200.2 255.255.255.0 0410 3088 CTCT 30880 192.168.100.2 30880 2048 0411 3088 CTCT 30881 192.168.100.2 30881 2048 0580 3420 ickdsf.ipl 0581 3420 /dev/st0 0582 3420 /cdrom/tapes/uaa196.tdf
Blank lines, and lines beginning with a pound sign ('#' - "hash" to Europeans) 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:
CPUSERIAL xxxxxx
CPUMODEL xxxx
MAINSIZE nnnn
nnnn is a decimal number
in the range is 2 to 1024
XPNDSIZE nnnn
nnnn is a decimal number
in the range is 0 to 1024
HTTPPORT nnnn [auth/noauth] [userid password]
CNSLPORT nnnn
NUMCPU nn
MAX_CPU_ENGINES
in the file hercules.h has a value of more than 1.
Multiprocessor emulation works best
if your system has more than physical CPU, but you can
emulate multiple CPUs even on a uniprocessor system
and you may still achieve a small performance benefit.
There is no point in specifying NUMCPU greater than 1 unless
your operating system is able to support multiple CPUs, and
if you do not need multiprocessor emulation then setting
MAX_CPU_ENGINES to 1 at compile time may improve performance.
NUMVEC nn
CPUPRIO nn
LOADPARM xxxxxxxx
SYSEPOCH yyyy
SYSEPOCH 1988 is recommended.
This makes the year 2000 appear to be 1972.
TZOFFSET ±hhmm
-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
OSTAILOR OS/390 | VM | VSE | LINUX
PANRATE SLOW | FAST | nn
ARCHMODE S/370 | ESA/390 | ESAME
S/370 for OS/360, VM/370, and MVS 3.8.
Use ESA/390 for MVS/XA, MVS/ESA, OS/390, VM/ESA, VSE/ESA,
Linux/390, and ZZSA.
Use ESAME for z/OS and zLinux.
When 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 | 1-n
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 n 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
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 your license for the software 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
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. This problem is being pursued with IBM linux. Meanwhile,
if OSTAILOR LINUX is specified, then this value defaults to
800 otherwise the value defaults to 0.
A comment preceded by a pound sign may be appended to any system parameter statement.
The remaining statements in the configuration file are device records. There must be one device record for each I/O device. The format of the device record is:
devnum devtype [arguments]
where:
devnum
devtype
| Device type | Description | Emulated by |
|---|---|---|
| 3270, 3287 | Local non-SNA 3270 | TN3270 client connection |
| 1052, 3215 | Console printer-keyboards | Telnet client connection |
| 1442, 2501, 3505 | Card readers | Disk file(s) (ASCII or EBCDIC) |
| 3525 | Card punch | Disk file (ASCII or EBCDIC) |
| 1403, 3211 | Line printers | Disk file (ASCII) |
| 3420, 3480 | Tape drives | Disk file, CDROM, or SCSI tape |
| 3088 | Channel-to-channel adapters | TCP socket |
| 3310, 3370, 9313 9332, 9335, 0336 0671 |
FBA direct access storage devices | Disk file |
| 2311, 2314, 3330 3340, 3350, 3375 3380, 3390, 9345 |
CKD direct access storage devices | Disk file |
arguments
If neither EBCDIC nor ASCII is specified, then the device handler
attempts to detect the format of the card image file when the device
is first accessed.
Auto-detection is not supported for socket devices, and the default
is ASCII if sockdev is specified.
Each file on the virtual tape can be in one of three
formats:
If you have any IBM manuals in Bookmanager format on CDROM,
you can see some examples of TDF files in the
\TAPES directory on the CDROM.
Additional arguments that allow you to control various HET settings
are:
(Note: The CTCI protocol is only for the Linux version of
Hercules. For Windows, use the CTCI-W32 protocol instead).
If the first parameter is not one of the recognized CTC emulation
types, then the driver will operate as in Hercules Version 1, using
Willem Konynenberg's vmnet package, as described in Axel Schwarzer's
CTCA 3088 document.
To allow access to a minidisk within a full-pack FBA DASD image
file, two additional arguments may be specified after the file
name:
Volumes larger than 2GB (for example, the 3390 model 3)
are supported by spreading the data across more than one file.
Each file contains a whole number of cylinders. The first file
(which contains cylinders 0-2518 in the case of a 3390) usually
has _1 as the last two characters of its name. The ckddasd driver
allocates the remaining files by replacing the last character of
the file name by the characters 2, 3, etc.
When CKD DASD images are spread across multiple files, you must
specify only the first file name (the file with suffix _1) in the
configuration statement!
Alternatively, the argument may specify the name of a file containing
a compressed CKD DASD image. The CKD driver will automatically detect
whether the file contains a regular CKD image or a compressed CKD
image. Refer to the CCKD page for details
of how to create and use compressed CKD DASD images.
sockdev
port or host:port
or sockpath/sockname. The device then accepts
remote connections on the given TCP/IP port or Unix Domain
Socket, and reads data from the socket instead of from a device
file. This allows automatic remote submission of card reader
data. See the Hercules Socket Reader
page for more details.
eof
multifile
ebcdic
ascii
trunc
autopad
ascii
ascii argument is not specified, the
file is written as fixed length 80-byte EBCDIC records with
no line-end delimiters.
crlf
crlf argument is not specified, then
line-feeds only are written at the end of each line.
crlf
crlf argument is not specified, then
line-feeds only are written at the end of each line.
TEXT
FIXED nnnnn
nnnnn)
HEADERS
AWSTAPE
COMPRESS=n
IDRC=n
n can be 1
to turn on compression (the default) or 0 to turn
it off. IDRC is a currently a synonym for
COMPRESS, but may be used in the future to
control other emulated tape drive features.
METHOD=n
LEVEL=n
CHUNKSIZE=nnnnn
nnnnn sized chunks. To be honest, I
can't think of a reason you'd want to change this since
decreasing it may reduce compression performance, but it's
there if you want it. The range is from 4096
to 65535. The latter being the default.
lport
rhost
rport
bufsize
origin
numblks
A comment preceded by a pound sign may be appended to any device definition statement.
If you have a question about Hercules, see the Hercules Frequently-Asked Questions page.
Last updated 3 July 2002