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 CODEPAGE default CNSLPORT 3270 HTTPPORT 8081 HTTPROOT /usr/local/share/hercules/ 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]
HTTPROOT directory
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.
CODEPAGEcodepage
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 | 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, 9336 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.
noprompt, if specified, will remove
    the message at the console prompting for input.
    
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
    intrq option.
    intrq
    eof
        option.
    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 1 February 2003