# Hercules Version 2: Configuration File

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.

### Example configuration file

    #
    # System parameters
    #

    CPUSERIAL 000611
    CPUMODEL  3090
    MAINSIZE  64
    XPNDSIZE  0
    CNSLPORT  3270
    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

### Comment lines

Blank lines, and lines beginning with a pound sign ('#' - "hash" to Europeans) or an asterisk, are treated as comments.

### System parameters

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`
  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
`MAINSIZE nnnn`
  specifies the main storage size in megabytes, where `nnnn` is a decimal number in the range is 2 to 256
`XPNDSIZE nnnn`
  specifies the expanded storage size in megabytes, where `nnnn` is a decimal number in the range is 0 to 1024
`CNSLPORT nnnn`
  specifies the port number (in decimal) to which tn3270 and telnet clients will connect
`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 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`
  specifies the number of emulated vector facilities. Default is one per CPU. Only available by default in ESA/390 mode.
`CPUPRIO nn`
  specifies 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). Hercules needs to be a setuid root program to allow it to reset is dispatching priority to a high (negative) value. (ie. chown root.root hercules; chmod +s 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 the TOD clock by a factor of nn, which can improve the performance of some operating systems which consume significant amounts of CPU time processing timer interrupts. Use of the TODDRAG parameter is no longer recommended.
`OSTAILOR OS/390 | VM | VSE | LINUX`
  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.
`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 | ESAME`
  specifies the initial architecture mode. Use `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`
  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 `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`.

A comment preceded by a pound sign may be appended to any system parameter statement.

### Device records

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`
  is a 1 to 4 digit hexadecimal number, in the range 0000 to FFFF (for ESA/390) or 0000 to 0FFF (for S/370). The device number uniquely identifies each device to the operating system.
`devtype`
  is the device type. Valid device types are:

  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`
  is a list of parameters whose meaning depends on the device type. The arguments required for each class of device are shown below.

### Arguments required for each device type

Local non-SNA 3270 devices
  No arguments are required for this device type. To use this device, a tn3270 client must connect to the host Linux machine via the port number specified in the CNSLPORT parameter. A valid tn3270 device type, such as IBM-3278, must be used. If your tn3270 client software allows you to specify a device type suffix (for example, IBM-3278@001F) then you can use the suffix to connect the client to a specific device number. If no suffix is specified, then the client will be connected to the first available 3270 device.

Console printer-keyboard devices
  No arguments are required for this device type. To use this device, a telnet client must connect to the host Linux machine via the port number specified in the CNSLPORT parameter. If your telnet client software allows you to specify a device type suffix (for example, ansi@0009) then you can use the suffix to connect the client to a specific device number. If no suffix is specified, then the client will be connected to the first available 1052 or 3215 device.

Card reader devices
  The argument specifies a list of file names containing card images. Additional arguments may be specified after the file names:

  `sockdev`
    indicates the card reader is a socket device wherein the filename is actually a socket specification instead of a device filename. When used, there must only be one filename specified in the form: `host:port`, where `host` is either an IP address or hostname and `port` is the port number. The device then accepts remote connections on the given `host:port` combination and reads data from the socket instead of a device file. This allows automatic remote submission of card reader data.
  `eof`
    specifies that unit exception status is presented after reading the last card in the file. If eof is not specified, then end of file results in unit check status with intervention required in the sense bytes.
  `multifile`
    specifies, when multiple input files are entered, to automatically open the next input file and continue reading whenever EOF is encountered on a given file. If not specified, then reading stops once EOF is reached on a given file and an attention interrupt is then required to open and begin reading the next file.
  `ebcdic`
    specifies that the file contains fixed length 80-byte EBCDIC records with no line-end delimiters.
  `ascii`
    specifies that the file contains variable length lines of ASCII characters delimited by LF (line feed) sequences or CRLF (carraige return line feed) sequences at the end of each line.

    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.

  `trunc`
    specifies, for ASCII files, that lines longer than 80 characters are truncated instead of producing a unit check error.
  `autopad`
    specifies, for EBCDIC files, that the file is automatically padded to a multiple of 80 bytes if necessary.

Card punch devices
  The argument specifies the name of a file to which the punched output will be written. Additional arguments may be specified after the file name:

  `ascii`
    specifies that the file will be written as variable length lines of ASCII characters delimited by line feeds or carriage return line feed sequences at the end of each line. Trailing blanks are removed from each line. If the `ascii` argument is not specified, the file is written as fixed length 80-byte EBCDIC records with no line-end delimiters.
  `crlf`
    specifies, for ASCII files, that carriage return line feed sequences are written at the end of each line. If the `crlf` argument is not specified, then line-feeds only are written at the end of each line.

Line printer devices
  The argument specifies the name of a file to which the printer output will be written. The output is written in the form of variable length lines of ASCII characters delimited by line feeds or by carriage return line feed sequences. Trailing blanks are removed from each line. Carriage control characters are translated to blank lines or ASCII form feed characters. If the file exists it will be overwritten. Additional arguments may be specified after the file name:

  `crlf`
    specifies, for ASCII files, that carriage return line feed sequences are written at the end of each line. If the `crlf` argument is not specified, then line-feeds only are written at the end of each line.

Emulated tape devices
  Four types of emulation are supported:

  SCSI tapes
    The argument specifies the tape device name (usually /dev/st0). SCSI tapes are read and written using variable length EBCDIC blocks and filemarks exactly like a mainframe tape volume.

  Optical Media Attach (OMA) virtual files
    These are read-only files which usually reside on CDROM. OMA virtual tapes consist of one CDROM file corresponding to each physical file of the emulated tape. An ASCII text file called the tape descriptor file (TDF) specifies the names of the files which make up the virtual tape. The argument specifies the name of the tape descriptor file (for example /cdrom/tapes/uaa196.tdf)

    Each file on the virtual tape can be in one of three formats:

    `TEXT`
      TEXT files consist of variable length ASCII records delimited by carriage return line feed sequences at the end of each record. Each record is translated to EBCDIC and presented to the program as one physical tape block.
    `FIXED nnnnn`
      FIXED files consist of fixed length EBCDIC blocks of the specified length (`nnnnn`)
    `HEADERS`
      HEADERS files consist of variable length EBCDIC blocks. Each block is preceded by a 12-byte header.

    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.

  AWSTAPE files
    These contain a complete tape in one file. AWSTAPE files consist of variable length EBCDIC blocks. Each block is preceded by a 6-byte header. Filemarks are represented by a 6-byte header with no data. This is the same format as is used by the P/390. The argument specifies the location of the AWSTAPE file (for example ickdsf.ipl)

  HET files
    These contain a complete tape in one file and have the same structure as the AWSTAPE format with the added ability to have compressed data. The first argument specifies the location of the HET file. The filename must end with ".het" to be recognized by Hercules as an HET file. (for example 023178.het)

    Additional arguments that allow you to control various HET settings are:

    `AWSTAPE`
      The AWSTAPE argument causes HET files to be written in AWSTAPE format. This basically, disables the additional features provided by the HET format.
    `COMPRESS=n`
    `IDRC=n`
      COMPRESS and IDRC control whether compression should be used when writing to HET files. The value `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`
      The METHOD option allows you to specify which compression method to use. You may specify 1 for ZLIB compression or 2 for BZIP2 compression. The default is 1.
    `LEVEL=n`
      The LEVEL option controls the level of compression. It ranges from 1 for fastest compression to 9 for best compression. The default is 4.
    `CHUNKSIZE=nnnnn`
      The CHUNKSIZE option allows you to create HET files that contain different chunk sizes. The AWSTAPE (and therefore the HET) format allows each tape block to be logically broken up into smaller chunks. For instance, if your S/3x0 application creates tapes with a block size of 27998, those blocks would be broken down into `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.

Channel-to-channel adapters
  The first argument defines the emulation type, and the remaining arguments depend on the emulation type. The following emulation types are defined:

  CTCI
    A point-to-point IP connection with the TCP/IP stack of the driving system on which Hercules is running. See the Hercules TCP/IP page for details.

  CTCT
    An emulated CTCA to another Hercules system. This is the only type of CTCA currently supported under Windows. Four arguments are required:
    `lport`
      specifies the local TCP port. This is the TCP port that Hercules will listen on for this CTCA.
    `rhost`
      specifies the remote host. This is the name or IP address of the remote system that Hercules is running on, not the name or IP address of the OS running on that copy of Hercules.
    `rport`
      specifies the remote TCP port. The rport parameter on this system must match the lport parameter on the remote system, and vice versa.
    `bufsize`
      specifies the buffer size for the link. If this link is used for IP traffic, this parameter should be more than the MTU of the interface definition in the OS.

  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.

FBA DASD devices
  The argument specifies the name of a file which contains the FBA DASD image. The file consists of fixed length 512-byte records, each of which represents one physical block of the emulated disk.

  To allow access to a minidisk within a full-pack FBA DASD image file, two additional arguments may be specified after the file name:

  `origin`
    specifies the relative block number within the DASD image file at which the minidisk begins. The number must be less than the number of blocks in the file. The default origin is zero.
  `numblks`
    specifies the number of 512-byte blocks in the minidisk. This number must not exceed the number of blocks in the file minus the origin. If omitted, or if specified as an asterisk, then the minidisk continues to the end of the DASD image file.

CKD DASD devices
  The argument specifies the name of a file containing the disk CKD DASD image. The file consists of a 512-byte device header record followed by fixed length track images. The length of each track image depends on the emulated device type, and is always rounded up to the next multiple of 512 bytes.

  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.

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 5 July 2001