# Hercules Version 3: 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

        ####################################################
        #     HERCULES EMULATOR CONFIGURATION FILE         #
        #     (Note: not all parameters are shown)         #
        ####################################################

        #
        #   System parameters
        #

        ARCHMODE   ESA/390
        OSTAILOR   OS/390
        LOADPARM   0120....

        CPUSERIAL  000611
        CPUMODEL   3090
        CPUVERID   FD
        LPARNAME   HERCULES
        MAINSIZE   64
        XPNDSIZE   0
        NUMCPU     1
        NUMVEC     1
        SYSEPOCH   1900
        TZOFFSET   -0500

        ##HTTPROOT   /usr/local/share/hercules/
        HTTPPORT   8081 NOAUTH

        CCKD       cache=8
        SHRDPORT   3990

        CNSLPORT   3270
        PANRATE    FAST
        CODEPAGE   default

        TODDRAG    1.0
        TODPRIO    -20
        HERCPRIO   0
        DEVPRIO    8
        CPUPRIO    15
        DEVTMAX    8

        DIAG8CMD   disable
        SHCMDOPT   disable

        AUTO_SCSI_MOUNT   no

        DEFSYM     TAPEDIR "$(HOME)/tapes"
        MODPATH    /usr/local/hercules
        LDMOD      dyncrypt

        ASN_AND_LX_REUSE  disable
        PGMPRDOS   restricted
        ECPSVM     no

        #
        #   Device definitions
        #

        0009      3215-C  /

        000A      1442    adrdmprs.rdr
        000C      3505    jcl.txt     ascii  trunc
        000D      3525    pch00d.txt  ascii
        000E      1403    prt00e.txt

        001F      3270    * 192.168.0.1
        0200.4    3270    * 192.168.0.0  255.255.255.0
        0220.8    3270    GROUP1  192.168.100.0  255.255.255.0
        0228.8    3270    GROUP2
        0230.16   3270

        0120      3380    mvsv5r.120
        0121      3380    mvsv5d.121
        0122      3380    mvswk1.122
        0123      3380    192.168.1.100

        0140      3370    dosres.140
        0141      3370    syswk1.141
        0300      3370    sysres.300

        0400      CTCT    30880  192.168.100.2  30880  2048
        0401      CTCT    30881  192.168.100.2  30881  2048
        0420.2    CTCI    192.168.200.1  192.168.200.2
        0440.2    LCS     -n   /dev/net/tun   192.168.200.2

        0580      3420    ickdsf.ipl
        0581      3420    /dev/nst0   # SCSI
        0582      3420    /cdrom/tapes/uaa196.tdf
        0583-0587 3420    $(TAPEDIR)/volumes.$(CUU) maxsizeM=170 eotmargin=131072

### Comment lines

Blank lines, and lines beginning with a # sign 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:

`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:

  - 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 `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"

`ECPSVM YES | NO | LEVEL nn`

  specifies whether ECPS:VM (Extended Control Program Support : Virtual Machine) support is to be enabled. If `YES` is specified, then the support level reported to the operating system is `20`. The purpose of ECPS:VM is to provide to the VM/370 Operating system a set of shortcut facilities to perform hypervisor functions (CP Assists) and virtual machine simulation (VM Assists). Although this feature does not affect VM Operating system products operating in XA, ESA or z/Architecture mode, it will affect VM/370 and VM/SP products running under VM/XA, VM/ESA or z/VM. Running VM/370 and VM/SP products under VM/XA, VM/ESA or z/VM should be done with ECPS:VM disabled. ECPS:VM should not be enabled in an AP or MP environment. ECPS:VM has no effect on non-VM operating systems. It is however recommended to disable ECPS:VM when running native non-VM operating systems. If a specific LEVEL is specified, this value will be reported to the operating system when it issues a Store ECPS:VM level, but it doesn't otherwise alter the ECPS:VM facility operations. This is a partial implementation.

`LDMOD module list`

  specifies additional modules that are to be loaded by the hercules dynamic loader. The default search order is with the hercules directory in the default DLL search path. Most systems also support absolute filenames (ie names starting with '/' or '.') in which case the default search path is not taken.

  Multiple LDMOD statements may be used.

`MODPATH path`

  specifies the path where dynamic modules are loaded from. When a modpath statement is specified, the path on the modpath statement is searched before the default path is searched. When a relative path is specified is interpreted as a relative path within the default search path, if an absolute path is specified is interpreted as such.

  The default MODPATH is hercules, which means modules are loaded from the directory hercules within the default LD_LIBRARY_PATH.

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

### Symbol substitutions

In configuration and device statements, as well as in panel commands, symbols may be substituted for text.

#### Syntax

To substitute symbol symbol with its contents, the symbol should be enclosed within parenthesis and preceded by a $ sign. For example, if symbol FOO contains the text string "BAR" then $(FOO) will be substituted with the string "BAR";. Symbol names are case sensitive.

##### Example

``

    ...
    DEFSYM TAPEDIR "/home/hercules/tapes"
    ...
    0380 3420 $(TAPEDIR)/scratch.aws
    ...

In this example, device 0380 will be a 3420 loaded with the AWS tape file in /home/hercules/tapes/scratch.aws

#### Special symbols

##### Device group symbols

When multiple devices are defined with a single device definition record, then the symbols

- CUU

: 3 digits device number, upper case hexadecimal digits

- CCUU

: 4 digits device number, upper case hexadecimal digits

- cuu

: 3 digits device number, lower case hexadecimal digits

- ccuu

: 4 digits device number, lower case hexadecimal digits

are defined to contain for each device the relevant device address. For example: `

    0200,0201 3340 /home/hercules/dasds/myvols.$(CUU)

`

Will define 2 3340 packs, with device 0200 being loaded with the file myvols.200 and device 0201 defined with myvols.201.

##### Environment variables

If a symbol is not explicitly defined by a DEFSYM statement and an environment variable by the same name exists, the string contents of that environment variable will be used for substitution.

##### Undefined symbols

If a symbol is not defined by an explicit DEFSYM, is not an automatically generated symbol or is not an environment variable, an empty string will be substituted.

#### Escaping substitution, recursion

To be able to specify the '$(' string without incurring substitution, an additional '$' sign should be used. For example, $$(FOO) will not be substituted. If substitution is required but the preceding text is to contain a '$' sign as the very last character, then $$$(FOO) should be specified. Thus, if symbol FOO contains "BAR", then $$(FOO) will remain "$$(FOO)" while $$$(FOO) will become "$BAR".

Substitution is NOT recursive (only one substitution pass is made).

### Process and Thread Priorities

#### Process Priorities

Note: Under Linux, a process is a thread and thread priority information applies instead.

For Windows, the following conversions are used for translating Unix process priorities to Windows process priority classes:

| Unix Priority |  | Windows Priority Class
--- | --- | --- | ---
| -20 | to | -16 |  | Realtime
| -15 | to | -9 |  | High
| -8 | to | -1 |  | Above Normal
| 0 | to | 7 |  | Normal
| 8 | to | 15 |  | Below Normal
| 16 | to | 20 |  | Low

#### Thread Priorities

On a *ix (Linux/Unix) host, Hercules needs to be a setuid root program to allow it to reset its dispatching priority to a high (negative) value (i.e., `chown root.root hercules; chmod +s hercules`).

For Windows, the following conversions are used for translating Linux/Unix thread priorities to Windows thread priorities:

| Unix Priority |  | Windows Priority
--- | --- | --- | ---
| -20 | to | -16 |  | Time Critical
| -15 | to | -9 |  | Highest
| -8 | to | -1 |  | Above Normal
| 0 | to | 7 |  | Normal
| 8 | to | 15 |  | Below Normal
| 16 | to | 19 |  | Lowest
| 20 |  |  |  | Idle

### Device definitions

The remaining statements in the configuration file are device records. There must be one device record for each I/O device or group of identical I/O devices. The format of the device record is:

> `devnum(s) devtype [ arguments ]`

where:

> `devnum(s)`

>   is either a single devnum, a range of devnums (separated by a '-' (dash)), a count of devnums (separated by a '.' (dot/period/stop)), or a comma separated list of devnums. Examples would be 200-210 or 0300.10 or 0400,0403 or 0100,0110-011F.

>   All devices defined when devnums specifies more than one device have identical characteristics (except for the device number itself). All devices defined as a group must be defined on a single channel. A channel is defined as a contiguous group of 256 (or hexadecimal 100) devices. 0010 and 0020 are on the same channels. 0100 and 0210 are not.

>   See devnum immediately below for an explanation of how each device number is specified.

>   The 4 special subtitution symbols CUU, CCUU, cuu and ccuu are also defined for each device in a device group. See substitutions for details.

> `devnum`

>   is either 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 shown in the table just below.

> `arguments`

>   is a list of parameters whose meaning depends on the device type. The arguments required for each class of device are shown below.

Supported Device Types
Device type | Description | Emulated by
--- | --- | ---
3270, 3287 | Local non-SNA 3270 display or printer | TN3270 client connection
1052, 3215 | Console printer-keyboards | Telnet client connection
1052-C, 3215-C | Integrated console printer-keyboards | Integrated on hercules console
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)
3410, 3420, 3480, 3490 9347, 8809, 3422, 3430 | Tape drives | Disk file, CDROM, or SCSI tape
3088 | Channel-to-Channel Adapter device | "CTCT" driver
(( CTCI )) | Channel-to-Channel link to host TCP/IP stack | "CTCI" TUN/TAP Driver
(( LCS )) | IBM 2216 router, IBM 3172 running ICP, IBM 8232 LCS device, LCS3172 driver of a P/390, IBM Open Systems Adapter (OSA) | "LCS" (LAN Channel Station) TUN/TAP Driver
3310, 3370, 9332, 9335 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
2703 | Communication Line | TCP Socket

#### Arguments required for each device type

Local non-SNA 3270 devices

  There are no required arguments for this particular device type, but there are however several optional arguments which are discussed below.

  To use this device, a tn3270 client must connect to the host machine via the port number specified on the CNSLPORT statement. 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 (e.g. `IBM-3278@001F` ), then you can use the suffix to connect to that specific device number, if eligible. If no suffix is specified, then your client will be connected to the first available 3270 device for which it is eligible, if any.

  If you specify a specific terminal device address (via the device type suffix of your tn3270 client software), then you must be eligible to connect at that device address or your connection is immediately rejected; an alternative terminal device for which you might be eligible is NOT automatically selected instead.

  Optional arguments:

  `groupname`

    If a terminal group name is given on the device statement, a device type suffix with this group name can be used to indicate that a device in this group is to be used. If a group name is specified as a terminal type suffix (e.g. `IBM-3278@GROUPNAME` ) and there are no devices defined for that group (or there are no more available devices remaining in that group), then the connection is rejected. If no group name is specified as a terminal type suffix, then the connection will only be eligible for any terminal devices which do not have a group name specified on their device statements. The terminal group name, if specified, should obviously not be a hexadecimal number.

  `ipaddr [ mask ]`

    The optional IP address and optional subnet mask specify the ip address(es) of which client(s) are allowed to connect at the device address identified by the device statement on which they appear. This provides an alternative and/or additional means of specifying to which device(s) a client tn3270 session may, or should, connect.

    If the IP address of the tn3270 client trying to connect, when 'and'ed with the optional subnet mask (which defaults to 255.255.255.255 if not specified), matches the IP address entered on the device statement, then the client is eligible to connect at that device address. Otherwise the client is ineligible to connect at that address and then next available device, if any, for which the client is eligible to connect (if any) is selected instead.

    If no permissible terminal devices remain (i.e. terminal devices for which the client is eligible to connect), or there are no more available terminal devices remaining, then the client connection is rejected.

    The optional IP address and subnet mask may also be specified in conjunction with the previously mentioned terminal group argument, but the terminal group argument, if specified, must be specified ahead of (i.e. before) the optional ip address and subnet mask arguments. To specify an IP address and subnet mask without also specifying a terminal group, simply use '*' as the group name instead.

    If an IP address / subnet mask are not specified, then any client tn3270 session is allowed to connect to the device (provided they are also a member of the specified terminal group, if any).

    The terminal group name argument, if specified, always takes precedence over any optional ip address and subnet mask which may also be specified.

  To summarize, the device number suffix always takes precedence over any group name which may also be specified, and any group name, if specified, always takes precedence over any ip address / subnet mask value which may also be specified.

Integrated Console printer-keyboard devices

  There is one optional argument which is the command prefix for sending input to the device. The default command prefix is '/'.

  Note: There is no restriction on the character you can select. If you select a command character that is the first character of a panel command, you will not be able to use that command.

  To send a logon command to a 1052-C or 3215-C enter /logon on the hercules console.

  All integrated devices must use a different command prefix.

Console printer-keyboard devices

  There are no required arguments for this particular device type, but there are however several optional arguments discussed below.

  To use this device, a telnet client must connect to the host machine via the port number specified on the CNSLPORT statement.

  If your telnet client software allows you to specify a device type suffix (for example: `ansi@0009` ), then you can use that suffix to specify the specific 1052 or 3215 device to which you wish to connect. If you do not specify a suffix in your telnet client software (or your software does not allow it), then your client will be connected to the first available 1052 or 3215 device for which it is eligible.

  An optional `noprompt` argument may be specified on the device statement to cause suppression of the "Enter input for console device nnnn" prompt message which is otherwise normally issued to the device whenever the system is awaiting input on that device.

  Additionally, a terminal group name, ip address and subnet mask may all also be optionally specified in the exact same manner as discussed in the previous Local non-SNA 3270 devices section with the exception that the "noprompt" option, if specified, must precede the other arguments.

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: `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`

    specifies that unit exception status is presented after reading the last card in the file. This option is persistent, and will remain in effect until the reader is reinitialized with the `intrq` option.

  `intrq`

    specifies that unit check status with intervention required sense bytes is presented after reading the last card in the file. This option is persistent, and will remain in effect until the reader is reinitialized with the `eof` option.

  `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. Auto-detection is not supported for socket devices, and the default is ASCII if sockdev is specified.

  `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.

  If the filename begins with the vertical bar '|' pipe character, then it is removed and the remainder of the device statement is interpreted as the name of an external program (followed by any necessary arguments) to which to "pipe" the printer output to. This is known as the "print-to-pipe" feature. All printer output is then sent to the piped program's stdin input, and all of the piped program's stdout and stderr output is piped back to Hercules for displaying on the hardware console.

Emulated tape devices

  Four types of emulation are supported:

  SCSI tapes

    The argument specifies the tape device name (usually `/dev/nst0`). SCSI tapes are read and written using variable length EBCDIC blocks and filemarks exactly like a mainframe tape volume. (See also the AUTO_SCSI_MOUNT configuration option).

  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 virtual 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 virtual 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. The range is from `4096` to `65535`, the latter being the default. Decreasing the value from its default may reduce compression performance. For compatability with AWSTAPE files created by the P/390, specify `AWSTAPE` with `CHUNKSIZE=4096`.

  The following parameters apply to both AWS and HET emulation files:

  `MAXSIZE`=n | `MAXSIZEK`=n | `MAXSIZEM`=n

    Specifies the maximum number of bytes (specified in bytes, Kilobytes or Megabytes) for the emulated file. This parameter defaults to 0, meaning there is no limit on the file size.

  `EOTMARGIN`=n

    Specifies the number of bytes remaining before reaching maxsize at which point the tape device will signal the presence of the 'End Of Tape' marker, thus allowing the program to switch to the next tape.

  Additionally, if the file name starts with the '@' character (at sign), the file really describes a list of tape emulation files to be loaded in succession.

  The syntax of each line is identical to the information specified that can be specified after the device type when the emulation file is specified directly after the device type in the configuration file.

  If the emulation file filename in the file list is the '*' character, then this specifies a set of options to be applied to all additional emulation files specified in the file list.

  Parameters are appended in succession. In all cases, is the same parameter is specified more than once, the last instance takes precedence.

  Therefore, it is possible to specify a set of parameters in the base configuration file, another set on a '*' line, and another set for each individual lines. Parameter are then appended in that order.

  A SCSI tape device should NOT be given in a file list.

  See the README.TAPE file for additional information, system and application programming for tape devices.

Channel-to-channel adapters

  The first argument defines the emulation type, and the remaining arguments depend on the chosen emulation type. If the first argument is not a recognized emulation type, 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.

  The following are the emulation types currently supported:

  CTCI (Channel to Channel link to TCP/IP stack)

    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.

    (Note: The CTCI protocol is only for the Linux version of Hercules. For Windows, use the below CTCI protocol instead).

  CTCI (Channel to Channel link to Win32 TCP/IP stack)

    A modified Win32 version of the CTCI protocol for the Windows crowd. Note that the protocol name (CTCI) is the same, even though the actual implementation is very different. See Fish's CTCI-W32 page for further details and information.

    Required for both Linux and Windows:

      `guestip`

        specifies the IP address of the guest operating system running under Hercules.

      `hostip`

        specifies the IP address of the host (Linux or Windows) side of the point-to-point link. This may or may not be the same as your system's regular IP address. For Windows, if the host system is configured with DHCP, this should instead be the MAC address of the Ethernet adapter you wish to use to have Hercules communicate with the outside world.

    Optional for Linux:

      If these arguments are specified, they must precede the required arguments.

      `-n name` or `--dev name`

        specifies the name of the tunnel device to use. The default is /dev/net/tun, which is correct for version 2.4 and above of the Linux kernel.

      `-d` or `--debug`

        specifies that debugging output is to be produced on the Hercules control panel. This should normally be left unspecified.

    Optional for Windows:

      If these arguments are specified, they must precede the required arguments. See Fish's CTCI-W32 page for further details and information.

  CTCT (Channel to Channel Emulation via TCP connection)

    An emulated CTCA to another Hercules system. 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.

    Note: CTCT currently only supports IP traffic, so it cannot be used to transport NJE, SNA, PVM, etc. type payloads. This may change in the future.

  LCS (LAN Channel Station Emulation)

    An emulated Lan Channel Station Adapter. This emulation mode appears to the operating system running in the Hercules machine as an IBM 8232 LCS device, an IBM 2216 router, a 3172 running ICP (Interconnect Communications Program), the LCS3172 driver of a P/390, or an IBM Open Systems Adapter.

    Rather than a point-to-point link, this emulation creates a virtual ethernet adapter through which the guest operating system running in the Hercules machine can communicate. As such, this mode is not limited to TCP/IP traffic, but in fact will handle any ethernet frame.

    The configuration statement for LCS is as follows:

    NOTE: There are no required parameters for the LCS emulation, however there are several options that can be specified on the config statement:

    NOTE: On the MAC OS X Platform, the long option format (--xxx) is not supported. Only the short option format (-x : one dash, one letter) should be used.

    `-n devname` or `--dev devname`

      where devname is:

      (*nix)

        the name of the TUN/TAP special character device, normally /dev/net/tun.

      (Windows)

        is either the IP or MAC address of the driving systems network card. TunTap32 will automatically select the first network card it finds if this option is omitted, this may not be desirable for some users.

    `-o filename` or `--oat filename`

      where filename specifies the filename of the Address Translation file. If this option is specified, the optional `--mac` and guestip entries are ignored in preference to statements in the OAT. (See further below for the syntax of the OAT file)

    `-m MAC Address` or `--mac MAC address`

      where MAC Address is the optional hardware address of the interface in the format: xx:xx:xx:xx:xx:xx. If you use the `--oat` option, do not specify an address here.

    `guestip`

      is an optional IP address of the Hercules (guest OS) side. Note: This is only used to establish a point-to-point routing table entry on driving system. If you use the `--oat` option, do not specify an address here.

    OAT file syntax

      The syntax for the Address Translation file is as follows:

          *********************************************************
          * Dev   Mode  Port  Entry specific information...       *
          *********************************************************

            0400  IP    00    PRI  172.021.003.032
            0402  IP    00    SEC  172.021.003.033
            0404  IP    00    NO   172.021.003.038
            0406  IP    01    NO   172.021.002.016
            040E  SNA   00

          HWADD  00  02:00:FE:DF:00:42
          HWADD  01  02:00:FE:DF:00:43

          ROUTE  00  172.021.003.032  255.255.255.224

      where:

        `Dev`
          is the base device address

        `Mode`
          is the operation mode: IP or SNA.

          Note: the SNA operation mode is NOT currently implemented.

        `Port`
          is the virtual (relative) adapter number.

      For IP modes, the entry specific information is as follows:

      `PRI | SEC | NO`

        specifies where a packet with an unknown IP address is forwarded to. PRI is the primary default entry, SEC specifies the entry to use when the primary is not available, and NO specifies that this is not a default entry.

      `nnn.nnn.nnn.nnn`

        specifies the home IP address

      When the operation mode is IP, specify only the even (read) device number dev. The odd (write) address will be create automatically.

      Note: the SNA operation mode is NOT currently implemented.

      Additionally, two other statements can be included in the address translation file. The HWADD and ROUTE statements.

      Use the HWADD to specify a hardware (MAC) address for a virtual adapter. The first parameter after HWADD specifies with relative adapter for which the address is applied.

      The ROUTE statement is included for convenience. This allows the hercifc program to create a network route for this specified virtual adapter. Please note that it is not necessary to include point-to-point routes for each IP address in the table. This is done automatically by the emulation module.

      The read/write devices can be swapped by coding the odd address of the even-odd pair in the OAT

      Up to 4 virtual (relative) adapters 00-03 are currently supported.

    If no Address Translation file is specified, the emulation module will create the following:

    An ethernet adapter (port 0) for TCP/IP traffic only.

    Two device addresses will be defined (devnum and devnum + 1).

CKD DASD devices

  The argument specifies the name of a file containing the disk CKD DASD image or the INET address of a Hercules shared device server.

  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) can be 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.

  Note: 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.

  If your operating system supports large file sizes (or 64-bit offsets) then volumes larger than 2G can be kept in a single file.

  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 "Creating an empty DASD volume" in the "Creating, formatting, and loading DASD volumes" section of the Creating DASD web page for information on using the 'dasdinit' command/utility to create compressed dasd files. Refer to the Compressed Dasd Emulation page for details on the actual CCKD emulation itself and additional information on the CCKD initialization/tuning control file statement.

  If you specify an INET address the format is:

  `ip-name-or-addr:port:devnum`

    ip-name-or-addr specifies the internet name or address where the Hercules shared device server is running.

    port specifies the port number the shared device server is listening on. If omitted, the default is 3990.

    devnum specifies the device number on the shared device server. If omitted, the default is the current device number.

  In addition to the above, some additional optional arguments are also supported.

  `sf=shadow-file-name`

    A shadow file contains all the changes made to the emulated dasd since it was created, until the next shadow file is created. The moment of the shadow file's creation can be thought of as a snapshot of the current emulated dasd at that time, because if the shadow file is later removed, then the emulated dasd reverts back to the state it was at when the snapshot was taken.

    Using shadow files, you can keep the base file on a read-only device such as cdrom, or change the base file attributes to read-only, ensuring that this file can never be corrupted.

    Hercules console commands are provided to add a new shadow file, remove the current shadow file (with or without backward merge), compress the current shadow file, and display the shadow file status and statistics

    For detailed information regarding shadow files and their use, please see the "Shadow Files" section of the Compressed Dasd Emulation web page.

  `[no]syncio`

    syncio enables possible 'synchronous' i/o. This is a dasd i/o feature wherein guest i/o requests are completed "synchronously" during the actual emulated execution of the SIO/SSCH (start-i/o / start subchannel) instruction rather than being deferred and executed asynchronously in a separate device i/o thread.

    Only i/o which are known to be able to be completed without actually needing to perform any actual host i/o are completed synchronously (e.g. whenever the data being requested is found to already be in cache). If the requested data is not found in the cache, then an actual host i/o will need to be done and the request is passed to a device i/o thread to be completed asyncronously instead.

    syncio is the default for ckd. syncio statistics may be displayed via the hercules `syncio` panel command.

    `syncio` may be abbreviated as `syio`

  `readonly`

    readonly returns "write inhibited" sense when a write is attempted. Note that not all of the sense bits may be getting set absolutely correctly however. (Some people have reported getting different error messages under hercules than a real machine, but it really hasn't been an issue for a while now.)

    `readonly` may be abbreviated as `rdonly` or `ro`

  `fakewrite`

    fakewrite is a kludge for the readonly sense problem mentioned above. Here the disk is not intended to be updated (MVS updates the DSCB last referenced field for a readonly file) and any writes appear to be successful even though nothing actually gets written.

    `fakewrite` may be abbreviated as `fakewrt` or `fw`

  `[no]lazywrite`
  `[no]fulltrackio`

    These options have been deprecated. They are still accepted, but they do absolutely nothing.

    `fulltrackio` may be abbreviated as `fulltrkio` or `ftio`

  `cu=type`

    Specifies the type of control unit to which this device is attached. The use of this parameter does not necessarily imply that all functions of the specified control unit are emulated, its only purpose is to force a particular control unit type to be indicated in the data returned by SENSE ID and similar CCW's.

    The default value depends on the device type:

    Device type | Default CU type</dev>
    --- | ---
    2311 2314 | 2841
    3330 3340 3350 3375 3380 | 3880
    3390 | 3990
    9345 | 9343

    Other values which may be specified are: 3990-3 3990-6

    Normally the default value is appropriate and this parameter need not be specified.

FBA DASD devices

  The argument specifies the name of a file which contains the FBA DASD image or the INET address of a Hercules shared device server.

  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.

  If you specify an INET address the format is:

  `ip-name-or-addr:port:devnum`

    ip-name-or-addr specifies the internet name or address where the Hercules shared device server is running.

    port specifies the port number the shared device server is listening on. If omitted, the default is 3990.

    devnum specifies the device number on the shared device server. If omitted, the default is the current device number.

  In addition to the above, some additional optional arguments are also supported.

  `sf=shadow-file-name`

    The handling of shadow files for FBA devices is identical as that for CKD devices. Please refer to the preceding CKD section for information regarding use of the `sf=` shadow file option.

  `[no]syncio`

    syncio enables possible 'synchronous' i/o and is explained in detail in the preceding CKD dasd section. Note however that syncio is currently disabled by default for FBA dasd due to an as yet unresolved problem and must therefore be specifically enabled if you wish to use it for FBA dasd.

    `syncio` may be abbreviated as `syio`

Communication Line

  ( Preliminary 2703 BSC Support )

  Describes a BSC emulation line entry to either link 2 hercules engines or a custom made program emulating a 2780, 3780 or 3x74, or a custom made program interfacing to a real BSC line.

  The communication is emulated over a TCP connection. All bytes are transfered as-is (except for doubling DLE in transparent mode) just like it would over a real BSC link. Emulated EIA (DCD, DTR, CTS, etc..) or X.21/V.11 leads (C, T, etc..) are treated differently depending on the DIAL option selected.

  The line emulates a point-to-point BSC link. There is no point-to-multipoint handling.

  The following options define the line emulation behaviour:

  `DIAL=IN | OUT | INOUT | NO`

    Specifies call direction (if any). If `DIAL=NO` is specified, the TCP outgoing connection is attempted as soon as an 'ENABLE' CCW is executed. Also, in this mode, an incoming connection will always be accepted. If `DIAL=IN|INOUT` is specified, a TCP incoming call is accepted ONLY if an 'ENABLE' CCW is currently executing on the device. If `DIAL=OUT`, the 'ENABLE' CCW is rejected. When `DIAL=IN|INOUT` is specified, a DIAL CCW allows the application to establish a TCP connection to a specific host. For other DIAL values, the DIAL CCW is rejected.

  `lhost=hostname | ip address | *`

    Specifies which IP address to listen on. This also conditions the network interface from which incoming calls will be accepted. Specifying '*' means all incoming TCP calls are accepted, regardless of the destination IP address or call origin. This is the default value. Specifying a specific IP address when `DIAL=OUT` is specified has no effect.

  `lport=service name | port number`

    Specifies the TCP port for which to listen to incoming TCP calls. This value is mandatory for `DIAL=IN|INOUT|NO`. It is ignored for `DIAL=OUT`.

  `rhost=hostname | ip address`
  `rport=service name | port number`

    Specifies the remote host and port to which to direct a TCP connection on a DIAL=NO line when an 'ENABLE' CCW is executed. This option is mandatory when `DIAL=NO` is specified. It is ignored for other `DIAL` values.

  The following options are tuning options. In most cases, using the default values give the best results

  `rto=0 | -1 | nnn | 3000`

    Specifies the number of milliseconds before terminating a read on a timeout, when no read termination control character is received. Specifying 0 means the READ ends immediately. -1 specifies there is no timeout.

  `pto=0 | -1 | nnn | 3000`

    Specifies the number of milliseconds before terminating a POLL on a timeout, when no ACK or NACK sequence is received. Specifying 0 means the POLL ends immediately. -1 specifies there is no timeout.

  `eto=0 | -1 | nnn | 10000`

    Specifies the number of milliseconds before terminating an ENABLE operation on a timeout. the timeout applies when `DIAL=NO|IN|INOUT` is specified, the outgoing TCP call fails (`DIAL=NO`) and there is no previously or currently established TCP connection for this line. When `DIAL=NO` is specified, the timeout defaults to 10 seconds. For `DIAL=IN|INOUT`, the timeout defaults to -1.

A comment preceded by a # 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 $Date: 2005/12/21 13:41:18 $ $Revision: 1.91 $