hercconf.html

<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 3.0//EN" "http://www.w3.org/TR/html4/loose.dtd">
<HTML><HEAD><TITLE>
Hercules: Configuration File
</TITLE>
<LINK REL=STYLESHEET TYPE="text/css" HREF="hercules.css">
<link rel="shortcut icon" href="images/favicon.ico" />
<link rel="icon" href="images/favicon.ico" />
</HEAD><BODY BGCOLOR="#ffffcc" TEXT="#000000" LINK="#0000A0" VLINK="#008040" ALINK="#000000">

<h1>Hercules Version 4: Configuration File</h1>

<p>
This page describes the configuration file for the Hercules S/370,
ESA/390, and z/Architecture emulator.
<p>
The configuration file <b><i>hercules.cnf</b></i> 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.
<h3>Example configuration file</h3>
<p>
<i>
<blockquote>
    <b>Please note</b> that the below example configuration file should
    <u>not</u> be considered a good example of how an actual configuration
    file should look! It is only meant to illustrate what some of the supported
    configuration file statements look like and how they are used.
</blockquote>
</i>
<p><br>
<center>
<table border=1><tr><td>
<pre><code>

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


    #------------------------------------------------------------------
    #                       <a href="#system_parameters">SYSTEM PARAMETERS</a>
    #------------------------------------------------------------------

    <a href="#HERCPRIO">##HERCPRIO</a>   0                                        (deprecated; unsupported)
    <a href="#HERCPRIO">##TODPRIO</a>    -20                                      (deprecated; unsupported)
    <a href="#HERCPRIO">##DEVPRIO</a>    8                                        (deprecated; unsupported)
    <a href="#HERCPRIO">##CPUPRIO</a>    0                                        (deprecated; unsupported)

    <a href="#ARCHLVL">##ARCHMODE</a>   ESA/390                                  (deprecated; use ARCHLVL)
    <a href="#ASN_AND_LX_REUSE">##ASN_AND_LX_REUSE</a>  disable                           (deprecated; use FACILITY)

    <a href="#PANRATE">##PANRATE</a>    FAST                                     (deprecated; use PANOPT)
    <a href="#PANTITLE">##PANTITLE</a>   "My own private MAINFRAME!"              (deprecated; use PANOPT)

    <a href="#ARCHLVL">ARCHLVL</a>    ESA/390
    <a href="#FACILITY">FACILITY</a>   ENABLE 044_PFPO

    <a href="#PGMPRDOS">PGMPRDOS</a>   restricted
    <a href="#ECPSVM">ECPSVM</a>     no  notrap

    <a href="#OSTAILOR">OSTAILOR</a>   OS/390
    <a href="#LOADPARM">LOADPARM</a>   0120....

    <a href="#CPUSERIAL">CPUSERIAL</a>  000611
    <a href="#CPUMODEL">CPUMODEL</a>   3090
    <a href="#CPUVERID">CPUVERID</a>   FD
    <a href="#LPARNAME">LPARNAME</a>   HERCULES
    <a href="#LPARNUM">LPARNUM</a>    01
    <a href="#CPUIDFMT">CPUIDFMT</a>   1
    <a href="#MODEL">MODEL</a>      EMULATOR
    <a href="#PLANT">PLANT</a>      ZZ
    <a href="#MANUFACTURER">MANUFACTURER</a> HRC

    <a href="#MAINSIZE">MAINSIZE</a>   1G
    <a href="#XPNDSIZE">XPNDSIZE</a>   0
    <a href="#NUMCPU">NUMCPU</a>     4
    <a href="#MAXCPU">MAXCPU</a>     8
    <a href="#ENGINES">ENGINES</a>    CP,CP,AP,IP

    <a href="#SYSEPOCH">SYSEPOCH</a>   1900
    <a href="#YROFFSET">YROFFSET</a>   -28
    <a href="#TZOFFSET">TZOFFSET</a>   -0500

    <a href="#HTTPPORT">HTTP</a>       PORT   8081  NOAUTH
    <a href="#HTTPROOT">HTTP</a>       ROOT   /usr/local/share/hercules/
    <a href="#HTTPSTRT">HTTP</a>       START

    <a href="#MODPATH">MODPATH</a>    /usr/local/hercules
    <a href="#LDMOD">LDMOD</a>      dyncrypt
    <a href="#NETDEV">NETDEV</a>     /dev/net/tun

    <a href="#CCKD">CCKD</a>       NOSFD=1
    <a href="#SHRDPORT">SHRDPORT</a>   3990

    <a href="#PANOPT">PANOPT</a>     NAMEONLY RATE=FAST MSGCOLOR=DARK "TITLE=My own private MAINFRAME!"
    <a href="#LOGOPT">LOGOPT</a>     TIMESTAMP NODATESTAMP

    <a href="#CODEPAGE">CODEPAGE</a>   819/1047
    <a href="#CNSLPORT">CNSLPORT</a>   3270
    <a href="#SYSGPORT">SYSGPORT</a>   3278
    <a href="#CONKPALV">CONKPALV</a>   (3,1,10)
    <a href="#LEGACYSENSEID">LEGACYSENSEID</a>   OFF

    <a href="#TIMERINT">TIMERINT</a>   DEFAULT
    <a href="#TODDRAG">TODDRAG</a>    1.0
    <a href="#DEVTMAX">DEVTMAX</a>    8

    <a href="#SHCMDOPT">SHCMDOPT</a>   disable  nodiag8
    <a href="#DIAG8CMD">DIAG8CMD</a>   disable  noecho
    <a href="#CMDSEP">CMDSEP</a>     OFF

    <a href="#DEFSYM">DEFSYM</a>     TAPEDIR   "<a href="#subs">$(HOME)</a>/tapes"
    <a href="#AUTOMOUNT">AUTOMOUNT</a>  $(TAPEDIR)
    <a href="#AUTOMOUNT">AUTOMOUNT</a>  +/tapes
    <a href="#AUTOMOUNT">AUTOMOUNT</a>  -/tapes/vault

    <a href="#MOUNTED_TAPE_REINIT">MOUNTED_TAPE_REINIT</a>  allow
    <a href="#AUTOINIT">AUTOINIT</a>   on
    <a href="#SCSIMOUNT">SCSIMOUNT</a>  no

    <a href="#INCLUDE">INCLUDE</a>    mydevs.cfg
    <a href="#IGNORE">IGNORE</a>     INCLUDE_ERRORS
    <a href="#INCLUDE">INCLUDE</a>    optdevs.cfg


    #------------------------------------------------------------------
    #                     <a href="#device_stmts">DEVICE STATEMENTS</a>
    #             (see supported <a href="#device_types_table">device types</a> table)
    #------------------------------------------------------------------

    0009      <a href="#consysc">3215-C</a>  /

    000A      <a href="#1442">1442</a>    adrdmprs.rdr
    000C      <a href="#3505">3505</a>    jcl.txt     ascii  trunc
    000D      <a href="#3525">3525</a>    pch00d.txt  ascii
    000E      <a href="#1403">1403</a>    prt00e.txt  append       cctape=legacy
    001E      <a href="#1403">3211</a>    192.168.200.1:1403 sockdev  fcb=legacy

    001F      <a href="#3270">3270</a>    * 192.168.0.1
    0200.4    <a href="#3270">3270</a>    * 192.168.0.0  255.255.255.0
    0220.8    <a href="#3270">3270</a>    GROUP1  192.168.100.0  255.255.255.0
    0228.8    <a href="#3270">3270</a>    GROUP2
    0230.16   <a href="#3270">3270</a>

    0000      <a href="#SYSG">SYSG</a>    SYSGCONS

    0100      <a href="#ckddasd">3390</a>    disks/linux.dsk  <a href="#shadow">sf=shadows/linux_*.dsk</a>  <a href="#ckdser">ser=000000000001</a>  <a href="#cu">cu=3990-6</a>

    0120      <a href="#3380">3380</a>    <a href="#ENHSYMINC">${DASD_PATH=dasd/}</a>mvsv5r.120
    0121      <a href="#3380">3380</a>    <a href="#ENHSYMINC">${DASD_PATH=dasd/}</a>mvsv5d.121
    0122      <a href="#3380">3380</a>    <a href="#ENHSYMINC">${DASD_PATH=dasd/}</a>mvswk1.122
    0123      <a href="#3380">3380</a>    192.168.1.100

    0140      <a href="#3370">3370</a>    dosres.140
    0141      <a href="#3370">3370</a>    syswk1.141
    0300      <a href="#3370">3370</a>    sysres.300

    0A00.3    <a href="#QETH">QETH</a>    chpid F0  iface /dev/net/tun  ipaddr 192.168.0.4  netmask 255.255.0.0
    0440.2    <a href="#LCS">LCS</a>     -n   /dev/net/tun   192.168.200.2
    0420.2    <a href="#CTCI">CTCI</a>    192.168.200.1  192.168.200.2
    0430.2    <a href="#CTCI">CTCI</a>    tun0
    #0E40      <a href="#LCS">LCS</a>     -e <a href="#SNA">SNA</a>  tap0
    0E40      <a href="#CTCE">CTCE</a>    31880  192.168.1.202  32880
    0E41      <a href="#CTCE">CTCE</a>    31882  192.168.1.202  32882

    0E42.2    <a href="#CTCE">CTCE</a>         1=192.168.1.202
    0460.2    <a href="#PTP">PTP</a>     192.168.200.1  192.168.200.2/24
    0470.2    <a href="#PTP">PTP</a>     tun0

    0580      <a href="#3420">3420</a>    ickdsf.aws  <a href="#noautomount">noautomount</a>
    0581      <a href="#3420">3420</a>    /cdrom/tapes/uaa196.tdf
    0582-0587 <a href="#3420">3420</a>    <a href="#subs">$(TAPEDIR)</a>/volumes.<a href="#subs">$(CUU)</a> maxsizeM=170 eotmargin=131072

    0590      <a href="#3420">3590</a>    \\.\Tape0   # <a href="#SCSI">SCSI</a>  (Windows only)
    0591      <a href="#3420">3590</a>    /dev/nst0   # <a href="#SCSI">SCSI</a>  (Linux or Windows)
    0592      <a href="#3420">3490</a>    /dev/nst1 <a href="#Quantum">--no-erg</a> <a href="#Quantum">--blkid-32</a>   # <a href="#Quantum">Quantum DLT SCSI</a>

    0020      <a href="#2703">2703</a>    lport=32003 dial=IN lnctl=tele2 uctrans=yes term=tty skip=88C9DF iskip=0A
    0023      <a href="#2703">2703</a>    lport=3780 rhost=localhost rport=3781 dial=no
    0045      <a href="#2703">2703</a>    lport=32003 dial=IN lnctl=ibm1 term=2741 skip=5EDE code=ebcd


</pre></code>
</td></tr></table>
</center>

<h3>Comment lines</h3>
<p>
    Blank lines, and lines beginning with a &#035; sign
    or an asterisk, are treated as comments.
    <p>

<hr><!-- ---------------------------------------------------------------------------- -->

<a name="system_parameters"></a>
<h3>System parameters</h3>
<p>
    Except for the ARCHLVL and LPARNUM statements, system parameter statements
    may appear in any order but must precede any device statements. Each system
    parameter must be on a separate line. The following system parameters may be
    specified:

<dl>

<a name="ARCHLVL"></a>
<dt><code>ARCHLVL &nbsp; S/370 &#124; ESA/390 &#124; ESAME &#124; <u>z/Arch</u></code>
<dd><p>
    Specifies the initial architecture mode:<p>
    <ul compact>
    <li>use <code>S/370</code> for OS/360, VM/370, and MVS 3.8.
    <li>use <code>ESA/390</code> for MVS/XA, MVS/ESA, OS/390, VM/ESA, VSE/ESA,
    Linux/390, and ZZSA.
    <li>use <code>z/Arch</code> or <code>ESAME</code> for z/OS and zLinux. This is the default.
    </ul>
    When <code>z/Arch</code> or <code>ESAME</code> 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.
    <p>
    When <code>ARCHLVL S/370</code> is set, the current
    <code><a href="#LPARNUM">LPARNUM</a></code> and
    <code><a href="#CPUIDFMT">CPUIDFMT</a></code> settings will be
    <i>automatically changed</i> to <code>BASIC</code>. When <code>ARCHLVL z/Arch</code>
    is set, <code>LPARNUM</code> and <code>CPUIDFMT</code> will be reset
    back to <code>1</code> and <code>0</code> respectively (if needed). Refer to
    the <i>"Limited automatic LPARNUM updating when setting certain architecture modes"</i>
    section of the <a href="hercrnot.html#4.1">Release Notes</a> document for more information.
    <p>
    The <code>ARCHLVL</code> statement used to be called <code>ARCHMODE</code>
    in previous versions of Hercules but the use of <code>ARCHMODE</code> has been
    deprecated in favor of the new <code>ARCHLVL</code> statement.
    Existing <code>ARCHMODE</code> statements should be changed to <code>ARCHLVL</code>
    instead. For the time being however, <code>ARCHMODE</code> is still accepted
    and is treated as simply a synonym for the <code>ARCHLVL</code> statement.
    <p>

<a name="ASN_AND_LX_REUSE"></a>
<dt><code>ASN_AND_LX_REUSE &nbsp; <u>ENABLE</u> &#124; DISABLE</code> &nbsp; &nbsp; &nbsp; <i>(deprecated; use FACILITY)</i>
<dd><p>
    Specifies whether the ASN-and-LX-Reuse Facility (ALRF) should be enabled
    or disabled. The default is enabled. This is a z/Architecture-only feature
    which is always disabled by default for S/390 or ESA/390.
    <p>
    Set this value to <code>ENABLE</code> &nbsp;(or do not specify anything
    at all) if your guest operating system supports or expects this feature.
    Set it to <code>DISABLE</code> &nbsp;if your guest operating system does
    <i>not</i> support this z/Architecture feature, and it inadvertently
    sets CR0 bit 44 to 1, usually leading to unexpected program interrupt
    when instructions such as LASP are issued.
    <p>
    <code>ASN_AND_LX_REUSE</code> may be abbreviated as <code>ALRF</code>.
    <p>
    <b>Note:</b> The <code>ASN_AND_LX_REUSE</code> statement has been superseded
    by "<code>FACILITY ENABLE/DISABLE 006_ASN_LX_REUSE</code>" and is thus deprecated.
    Existing <code>ASN_AND_LX_REUSE</code> or <code>ALRF</code> statements
    should be changed to use the new <a href="#FACILITY">FACILITY</a>
    statement format instead.
    <p>

<a name="AUTOINIT"></a>
<dt><code>AUTOINIT &nbsp; <u>ON</u> &#124; OFF</code>
<dd><p>
    The <code>AUTOINIT</code> option controls whether device files
    for emulated tape volumes should be automatically created or not.
    <p>
    When <code>AUTOINIT</code> is <code>ON</code>, a devinit command
    specifying a file that does not yet exist causes the tape driver
    to automatically create an empty unlabeled tape volume consisting
    of just two tapemarks when it discovers the specified file
    does not exist yet.
    When <code>AUTOINIT</code> is <code>OFF</code> a devinit command
    instead fails with an expected "file not found" error.
    For convenience the default setting is <code>ON</code>.


<a name="AUTOMOUNT"></a>
<dt><code>AUTOMOUNT &nbsp; <em>[&plusmn;]directory</em></code>
<dd><p>
    Specifies the host system directory where the guest is allowed
    or not allowed to automatically load virtual tape volumes from.
    Prefix allowable directories with a '+' plus sign and unallowable
    directories with a '-' minus sign. The default prefix if neither is
    specified is the '+' plus sign (i.e. an allowable directory).
    <p>
    <i><b><u>Caution</u>:</b> &nbsp;Enabling this feature may have security
    consequences depending on which allowable host system directories you
    specify as well as how your guest operating system enforces
    authorized use of the Set Diagnose (X'4B') channel command code.
    </i>
    <p>
    All host system virtual tape volumes to be "automounted" by the guest
    must reside within one of the specified allowable host system directories
    or any of its subdirectories while not also being within any of the
    specified unallowable directories or any of their subdirectories,
    in order for the guest-invoked automount to be accepted.
    <p>
    Note: specifying a disallowed automount directory does not preclude the
    Hercules operator from manually mounting any desired file via the
    <code>devinit</code> panel command -- even one in a currently defined
    "disallowed" automount directory. The AUTOMOUNT statement only controls
    guest-invoked automatic tape mounts and not manual tape mounts performed
    by the Hercules operator.
    <p>
    All directories must be specified on separate statements, but as many
    statements as needed may be specified in order to describe the desired
    allowable/unallowable directories layout. For convenience, an
    <code>automount</code> panel command is also provided to dynamically
    add/remove new/existing allowable/unallowable automount
    directories at any time.
    <p>
    The automount feature is activated whenever you specify at least
    one allowable or unallowable directory. If only
    unallowable directories are specified, then the current directory
    becomes the only defined allowable automount directory by default.
    <p>
    All specified directories are always resolved to fully-qualified
    absolute directory paths before being saved.
    <p>
    Refer to the description of the virtual tape device
    '<a href="#noautomount">noautomount</a>' option for more information.
    <p>

<a name="CCKD"></a>
<dt><code>CCKD &nbsp; <em>cckd-parameters</em></code>
<dd><p>
    The CCKD command and initialization statement can be used to affect
    cckd processing. The CCKD initialization statement is specified as
    a Hercules configuration file statement and supports the same options
    as the cckd panel command. Refer to the
    <a href="cckddasd.html#cckdcommand">Compressed Dasd Emulation</a>
    web page for more information.
    <p>

<a name="CMDSEP"></a>
<dt><code>CMDSEP &nbsp; <u>OFF</u> &#124; <em>c</em></code>
<dd><p>
    A command line separator character allows multiple commands to be
    entered on a single line. The character '<i><code>c</code></i>'
    defines the command separator character. The values
    '<i><code>.</code></i>' (period or dot),
    '<i><code>!</code></i>' (exclamation mark or bang) and
    '<i><code>-</code></i>' (dash or hypen)
    are reserved and cannot be used.
    The default value is 'OFF' indicating command separation is disabled.
    <p>

    <i>
    <b>Warning:</b> choose your separator character carefully. Setting it
    to an alphabetic value for example disables all commands containing
    that character. Setting it to '<code>e</code>' for example will disable
    the 'exit' command making it impossible to exit the emulator. Similarly,
    setting it to '<code>o</code>' or '<code>f</code>' will make it impossible
    to disable command separation once enabled, and setting it to
    '<code>#</code>' (hash) will prevent lines with comments from being
    processed correctly.
    </i>

    <p>

<a name="CMPSCPAD"></a>
<dt><code>CMPSCPAD &nbsp; <em>alignment</em></code>
<dd><p>
    The CMPSCPAD command and initialization statement is used to define
    the zero padding storage alignment boundary for the CMPSC-Enhancement
    Facility. It must be a power of 2 value ranging anywhere from 1 to 12.
    <p>

<a  name="CNSLPORT"></a>
<dt><code>CNSLPORT &nbsp; <i><u>3270</u></i> &nbsp;<i>-or-</i> &nbsp;<i>nnnn</i> &nbsp;<i>-or-</i> &nbsp;<i>host:port</i></code>
<dd><p>
    Specifies (typically) the port number (in decimal) to which tn3270
    and telnet clients should connect. If an invalid value is specified
    Hercules defaults to port number <u>3270</u>.
    See also the <a href="#SYSGPORT"><code>SYSGPORT</code></a> statement.
    <p>
    The <code>CNSLPORT</code> statement may also be specified as
    <code>host:port</code>, where <code>host</code> identifies the
    IP address of the host interface the telnet console server should
    bind to (listen for connections on). If not specified the server
    will accept connections on the port from any host interface.
    <p>
    See the <a href="telnet.html">Telnet/tn3270 Console How-To</a>
    for additional information about setting up a telnet or tn3270 client.
    <p>

<a name="CODEPAGE"></a>
<dt><code>CODEPAGE &nbsp; <em>mapping</em></code>
<dd><p>
    Specifies the codepage conversion mapping table used for ASCII/EBCDIC translation.
    <p>

    <code>default</code> specifies traditional Hercules codepage mapping,
    which is non-transparent.

    <p>

    Other supported predefined codepage mappings are:
    <p>

    <blockquote>
    <table border=1 cellpadding=3>
        <tr>
          <th rowspan=2>Mapping</th>
          <th colspan=2>Description</th>
          <th rowspan=2>Transparent?</th>
        </tr>
        <tr>
          <th>ASCII</th>
          <th>EBCDIC</th>
        </tr>
        <tr><td align="center"><code>437/037</code></td>
            <td>437 PC United States</td>
            <td>037 United States/Canada</td>
            <td><center>no</center></td>
        </tr>

        <tr><td align="center"><code>437/500</code></td>
            <td>437 PC United States</td>
            <td>500 International</td>
            <td><center>no</center></td>
        </tr>

        <tr><td align="center"><code>437/1047</code></td>
            <td>437 PC United States</td>
            <td>1047 Open Systems Latin 1</td>
            <td><center>no</center></td>
        </tr>

        <tr><td align="center"><b><code>819/037</code></b></td>
            <td><b>819 ISO-8859-1</b></td>
            <td><b>037 United States/Canada</b></td>
            <td><b><center>YES</center></b></td>
        </tr>

        <tr><td align="center"><code>819/037v2</code></td>
            <td>819 ISO-8859-1</td>
            <td>037 United States/Canada version 2</td>
            <td><center>YES</center></td>
        </tr>

        <tr><td align="center"><code>819/273</code></td>
            <td>819 ISO-8859-1</td>
            <td>273 Austria/Germany</td>
            <td><center>YES</center></td>
        </tr>

        <tr><td align="center"><code>819/277</code></td>
            <td>819 ISO-8859-1</td>
            <td>277 Denmark/Norway</td>
            <td><center>YES</center></td>
        </tr>

        <tr><td align="center"><code>819/278</code></td>
            <td>819 ISO-8859-1</td>
            <td>278 Finland/Sweden</td>
            <td><center>YES</center></td>
        </tr>

        <tr><td align="center"><code>819/280</code></td>
            <td>819 ISO-8859-1</td>
            <td>280 Italy</td>
            <td><center>YES</center></td>
        </tr>

        <tr><td align="center"><code>819/284</code></td>
            <td>819 ISO-8859-1</td>
            <td>284 Spain</td>
            <td><center>YES</center></td>
        </tr>

        <tr><td align="center"><code>819/285</code></td>
            <td>819 ISO-8859-1</td>
            <td>285 United Kingdom</td>
            <td><center>YES</center></td>
        </tr>

        <tr><td align="center"><code>819/297</code></td>
            <td>819 ISO-8859-1</td>
            <td>297 France</td>
            <td><center>YES</center></td>
        </tr>

        <tr><td align="center"><b><code>819/500</code></b></td>
            <td><b>819 ISO-8859-1</b></td>
            <td><b>500 International</b></td>
            <td><b><center>YES</center></b></td>
        </tr>

        <tr><td align="center"><b><code>819/1047</code></b></td>
            <td><b>819 ISO-8859-1</b></td>
            <td><b>1047 Open Systems Latin 1</b></td>
            <td><b><center>YES</center></b></td>
        </tr>

        <tr><td align="center"><code>850/273</code></td>
            <td>850 PC Latin 1</td>
            <td>273 Austria/Germany</td>
            <td><center>YES</center></td>
        </tr>

        <tr><td align="center"><code>850/1047</code></td>
            <td>850 PC Latin 1</td>
            <td>1047 Open Systems Latin 1</td>
            <td><center>no</center></td>
        </tr>

        <tr><td align="center"><code>1252/037</code></td>
            <td>1252 Windows Latin 1</td>
            <td>037 United States/Canada</td>
            <td><center>no</center></td>
        </tr>

        <tr><td align="center"><code>1252/037v2</code></td>
            <td>1252 Windows Latin 1</td>
            <td>037 United States/Canada version 2</td>
            <td><center>no</center></td>
        </tr>

        <tr><td align="center"><code>1252/1047</code></td>
            <td>1252 Windows Latin 1</td>
            <td>1047 Open Systems Latin 1</td>
            <td><center>no</center></td>
        </tr>

        <tr><td align="center"><code>1252/1140</code></td>
            <td>1252 Windows Latin 1</td>
            <td>1140 United States/Canada with Euro</td>
            <td><center>YES</center></td>
        </tr>

        <tr><td align="center"><b><code>ISOANSI/037</code></b></td>
            <td><b>ISO ANSI</b></td>
            <td><b>037 United States/Canada</b></td>
            <td><b><center>YES</center></b></td>
        </tr>

    </table>
    </blockquote>
    <p>

    The transparency column indicates whether translating from
    ASCII to EBCDIC (or vice versa) and back again yields results
    identical to the original text.

    <p>

    If no codepage is specified then the environment variable HERCULES_CP
    will be inspected. If the environment variable is not found then
    the traditional non-transparent <code>default</code> codepage mapping
    is used.

    <p>

    Other codepages can be defined by means of the <code>cp_updt</code>
    panel command (which is supported as a configuration file statement
    as well). Enter the panel command <code>help cp_updt</code> for more
    information.

    <p>

    The recommended code page for Linux guests is
    "<b>819/500</b>",
    as it is both transparent and appears to be the code
    page that s390x Linux actually uses, thus allowing
    boot/startup messages to be parsed and displayed properly.

    <p>

    The recommended code page for non-Linux guests (e.g. z/OS, etc) is
    "<b>819/1047</b>", as it is both transparent and properly translates
    all ASCII characters to their EBCDIC equivalents,
    including all extended ASCII characters too, such as:

    <p>

<blockquote>
<table style="width:25%">

<tr><td style="text-align:center">!</td><td style="text-align:left"> &nbsp; &nbsp; exclamation point</td></tr>
<tr><td style="text-align:center">[</td><td style="text-align:left"> &nbsp; &nbsp; left square bracket</td></tr>
<tr><td style="text-align:center">]</td><td style="text-align:left"> &nbsp; &nbsp; right square bracket</td></tr>
<tr><td style="text-align:center">{</td><td style="text-align:left"> &nbsp; &nbsp; left curly bracket</td></tr>
<tr><td style="text-align:center">}</td><td style="text-align:left"> &nbsp; &nbsp; right curly bracket</td></tr>
<tr><td style="text-align:center">|</td><td style="text-align:left"> &nbsp; &nbsp; solid vertical bar</td></tr>
<tr><td style="text-align:center">&brvbar;</td><td style="text-align:left"> &nbsp; &nbsp; broken vertical bar</td></tr>
<tr><td style="text-align:center">\</td><td style="text-align:left"> &nbsp; &nbsp; backslash</td></tr>
<tr><td style="text-align:center">&not;</td><td style="text-align:left"> &nbsp; &nbsp; logical not</td></tr>
<tr><td style="text-align:center">^</td><td style="text-align:left"> &nbsp; &nbsp; caret / circumflex</td></tr>
<tr><td style="text-align:center">_</td><td style="text-align:left"> &nbsp; &nbsp; underscore</td></tr>
<tr><td style="text-align:center">`</td><td style="text-align:left"> &nbsp; &nbsp; grave accent</td></tr>
<tr><td style="text-align:center">~</td><td style="text-align:left"> &nbsp; &nbsp; tilde</td></tr>
<tr><td style="text-align:center">&cent;</td><td style="text-align:left"> &nbsp; &nbsp; cent</td></tr>
<tr><td style="text-align:center">&pound;</td><td style="text-align:left"> &nbsp; &nbsp; pound</td></tr>
<tr><td style="text-align:center">&curren;</td><td style="text-align:left"> &nbsp; &nbsp; currency sign</td></tr>
<tr><td style="text-align:center">&yen;</td><td style="text-align:left"> &nbsp; &nbsp; yen</td></tr>
<tr><td style="text-align:center">&sect;</td><td style="text-align:left"> &nbsp; &nbsp; section sign</td></tr>
<tr><td style="text-align:center">&para;</td><td style="text-align:left"> &nbsp; &nbsp; pilcrow/paragraph</td></tr>
<tr><td style="text-align:center">&copy;</td><td style="text-align:left"> &nbsp; &nbsp; copyright symbol</td></tr>
<tr><td style="text-align:center">&reg;</td><td style="text-align:left"> &nbsp; &nbsp; registered trademark</td></tr>
<tr><td style="text-align:center">&ordf;</td><td style="text-align:left"> &nbsp; &nbsp; feminine ordinal indicator</td></tr>
<tr><td style="text-align:center">&deg;</td><td style="text-align:left"> &nbsp; &nbsp; degree</td></tr>
<tr><td style="text-align:center">&ordm;</td><td style="text-align:left"> &nbsp; &nbsp; masculine ordinal indicator</td></tr>
<tr><td style="text-align:center">&plusmn;</td><td style="text-align:left"> &nbsp; &nbsp; plus-minus</td></tr>
<tr><td style="text-align:center">&micro;</td><td style="text-align:left"> &nbsp; &nbsp; mu/micro</td></tr>
<tr><td style="text-align:center">&iquest;</td><td style="text-align:left"> &nbsp; &nbsp; inverted question mark</td></tr>
<tr><td style="text-align:center">&times;</td><td style="text-align:left"> &nbsp; &nbsp; multiplication sign</td></tr>
<tr><td style="text-align:center">&divide;</td><td style="text-align:left"> &nbsp; &nbsp; obelus/divide sign</td></tr>

</table>
</blockquote>

    <p>

<a name="CONKPALV"></a>
<dt><code>CONKPALV &nbsp; <i>(idle,intv,count)</i></code>
<dd><p>
    Specifies the tn3270 console and telnet clients keepalive option
    values that control automatic detection of disconnected tn3270/telnet
    client sessions.
    <p>
    <code><i>idle</i></code> &nbsp;specifies the number of seconds
    of inactivity until the first keepalive probe is
    sent (idle time until first probe, or probe frequency).
    <br><code><i>intv</i></code> &nbsp;
    specifies the interval in seconds between when successive
    keepalive packets are sent if no acknowledgement is received from
    the previous one (i.e. the timeout value of the probes themselves).
    <br><code><i>count</i></code> &nbsp;specifies the number of unacknowledged
    keepalive packets sent before the connection is considered to have
    failed.
    <p>
    The default values for Windows are 3, 1, and 10. For non-Windows systems
    it is 3, 1, and 9. That is, send the initial probe 3 seconds after the
    connection goes idle and then wait no more than one second for it to be
    responded to. If it is not responded to within one second, then send up
    to 9 more probes (for a total of 10), each of which must also timeout
    without being responded to before the client is considered as having
    died and the connection thus automatically closed.
    <p>
    <i><b>Note:</b></i>
    This is a built-in feature of TCP/IP and allows detection of
    unresponsive TCP/IP <i>connections</i> and not idle clients.
    That is to say, your connection will <i>not</i> be terminated
    after 3 seconds of idle time. Your 3270 session can remain idle for
    many minutes or hours or days without any data being transmitted.
    If the TCP/IP <i>stack</i> at the other end of the connection --
    not your 3270 client itself -- fails to respond to the
    internal keepalive probe packets however, then it means that the
    TCP/IP stack itself is down or there has been a physical break
    in the connection.
    <p>
    Thus, even if your 3270 client is completely idle, your system's TCP/IP stack
    itself should still respond to the keepalive probes sent by the TCP/IP stack
    at the Hercules end of the link. If it doesn't, then TCP/IP will terminate
    the tn3270/telnet session which will cause Hercules to disconnect the terminal.
    <p>
    The three values can also be modified on-demand via the <code>conkpalv</code>
    panel command, which has the exact same syntax. Note that the syntax is
    very unforgiving: no spaces are allowed anywhere within the parentheses
    and each value must be separated from the other with a single comma.
    <p>
    <b>Please also note</b> that not all systems support being able to modify
    all three values. That is, not all values may be modifiable. It is operating
    system dependent which values you can change and which values you cannot.
    On Windows for example, the <code><i>count</i></code> value is ignored
    and cannot be changed from its default value of 10. Other systems may
    ignore one or more or all three values and use platform defaults instead.
    This is entirely system dependent. Check your system's documentation for details
    regarding which values can be changed and which cannot as well as how to
    adjust your system's default values.
    <p>

<a name="CPUIDFMT"></a>
<dt><code>CPUIDFMT &nbsp; <u>0</u> &#124; 1 &#124; BASIC</code>
<dd><p>
    Specifies the format of the CPU ID the STIDP instruction should store.
    Refer to the <a href="#LPARNUM">LPARNUM</a> statement for more information.
    <p>

<a name="CPUMODEL"></a>
<dt><code>CPUMODEL &nbsp; <u>0586</u> &#124; <em>xxxx</em> &#124; <em>$(symbol)</em></code>
<dd><p>
    Specifies the 4 hexadecimal digit CPU machine type number (known prior
    to ESA/390 as the model number) stored by the STIDP instruction.
    <p>
    To make it easier to specify the model number for certain known models,
    the following <a href="#DEFSYM">symbols</a> are now automatically
    predefined starting with Hercules version 4.4:
    <p>
        <table style="width:25%">
          <tr>
            <th>Symbol</th>
            <th>Model</th>
          </tr>
          <tr>
            <td style="text-align:center"><code>zPDT</code></td>
            <td style="text-align:center"><code>1090</code></td>
          </tr>
          <tr>
            <td style="text-align:center"><code>EC12</code></td>
            <td style="text-align:center"><code>2827</code></td>
          </tr>
          <tr>
            <td style="text-align:center"><code>BC12</code></td>
            <td style="text-align:center"><code>2828</code></td>
          </tr>
          <tr>
            <td style="text-align:center"><code>z13</code></td>
            <td style="text-align:center"><code>2964</code></td>
          </tr>
          <tr>
            <td style="text-align:center"><code>z13s</code></td>
            <td style="text-align:center"><code>2965</code></td>
          </tr>
          <tr>
            <td style="text-align:center"><code>z14</code></td>
            <td style="text-align:center"><code>3906</code></td>
          </tr>
          <tr>
            <td style="text-align:center"><code>z14ZR1</code></td>
            <td style="text-align:center"><code>3907</code></td>
          </tr>
          <tr>
            <td style="text-align:center"><code>z15</code></td>
            <td style="text-align:center"><code>8561</code></td>
          </tr>
          <tr>
            <td style="text-align:center"><code>z15T02</code></td>
            <td style="text-align:center"><code>8562</code></td>
          </tr>
          <tr>
            <td style="text-align:center"><code>z16</code></td>
            <td style="text-align:center"><code>3931</code></td>
          </tr>
        </table>
    <p>
    <i><b>Note:</b> Hercules makes no attempt to emulate all aspects of,
    or features of, a given CPU model. The CPUMODEL statement defines a purely
    cosmetic value only. It defines only the value that the STIDP (Store CPU
    ID) instruction stores, and nothing more.</i>
    <p>

<a name="CPUSERIAL"></a>
<dt><code>CPUSERIAL &nbsp; <u>000001</u> &#124; <em>xxxxxx</em></code>
<dd><p>
    Specifies the 6 hexadecimal digit CPU serial number stored by the
    STIDP instruction. In BASIC mode, the high-order digit may be
    replaced with the processor number when MAXCPU > 1; in LPAR mode,
    the two high-order digits are replaced with either the LPAR number
    or the CPU number and LPAR number with the full serial number
    available via the STSI instruction. The default serial number is
    <code>000001</code>.
    <p>

<a name="CPUVERID"></a>
<dt><code>CPUVERID &nbsp; <u>FD</u> &#124; <em>xx</em> &nbsp; [FORCE]</code>
<dd><p>
    Specifies the 2 hexadecimal digit CPU version code stored by the STIDP
    instruction.
    <p>
    The default cpuverid version code at startup is <b>FD</b>, and that value will
    be stored by the STIDP instruction -- <i>even for z/Arch</i> -- unless and <i>UNTIL</i>
    you set it to a different value via the <code>cpuverid</code> command/statement.
    <p>
    If you try using the <code>cpuverid</code> command/statement to set a non-zero cpuverid
    value when the architecture mode is currently set to z/Arch, the version
    code stored by the STIDP instruction will <i><u>still</u></i> be stored as 00 anyway,
    <i><u>unless</u></i> ... the <code>FORCE</code> option is used. For z/Arch, the <code>FORCE</code> option is
    the <i><u>only</u></i> way to cause the cpuverid command to force the STIDP instruction
    to store a non-zero version code. (But as explained, at startup, the value
    stored will still be FD even for z/Arch, since that is Hercules's default version
    code value. This means if you want your STIDP version code to be 00 for <b>z/Arch</b>, then you
    <i><u>must</u></i> use a <code>cpuverid</code> command/statement in your configuration file
    to set it to that value.)
    <p>

<a name="DEFSYM"></a>
<dt><code>DEFSYM &nbsp; <em>symbol</em> <em>value</em></code>
<dd><p>
    Defines symbol <em>symbol</em> as to contain value <em>value</em>. The
    symbol can then be the object of a substitution later in the configuration
    file or for panel commands. If <em>value</em> contains blanks or spaces, then
    it should be enclosed in double quotation marks (&quot;). See
    <a href="#subs">substitutions</a> for a more in-depth discussion
    on this feature.
    <p>
    Substitution is available even in configuration statements,
    meaning it is possible to perform substitution in the <em>DEFSYM</em> 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:
    <code><pre>
    DEFSYM FOO $(FOO)</pre></code>
    Will set symbol FOO to &quot;&quot;
    <p>

<a name="DEVTMAX"></a>
<dt><code>DEVTMAX &nbsp; -1 &#124; 0 &#124; <em>nnn</em></code>
<dd><p>
    Specifies the maximum number of device threads allowed.
    <p>Specify <code>-1</code> 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.
    <p>Specify <code>0</code> 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 <code>0</code> means there is no limit to the
    number of threads that can be created.
    <p>Specify a value from <code>1</code> to <code><em>nnn</em></code> &nbsp;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 <code>0</code> 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 <i>only</i> 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.
    <p>The default for Windows is <code>8</code>. The default for all other systems
    is <code>0</code>.
    <p>

<a name="DIAG8CMD"></a>
<dt><code>DIAG8CMD &nbsp; <u>DISABLE</u> &#124; ENABLE &nbsp; [ECHO &#124; <u>NOECHO</u>]</code>
<dd><p>
    When <code>ENABLE</code> is specified the Hercules Diagnose 8 instruction command
    interface is enabled, allowing the guest to directly issue Hercules commands via
    the Diagnose 8 instruction. When set to <code>DISABLE</code> all Diagnose 8 instructions
    cause a Specification Exception program interrupt to occur instead.
    <p>

    An optional second argument can be given to request whether an audit trail of such
    commands should be created or not. When <code>ECHO</code> is specified, a message
    is issued when the command is about to be issued, when the command is redisplayed (as
    is normally done when entered from the command line), as well as a final message
    indicating the command has finished executing. When <code>NOECHO</code> is specified
    no such audit trail messages are displayed and the command instead completes silently
    (except for whatever messages the command itself may issue).
    <p>

    <i><b><u>Security Alert</u>:</b> &nbsp;Enabling this feature has security consequences.
    When this feature is enabled it is possible for guest operating systems running under
    Hercules to issue commands directly to the host operating system by means of the
    <code>sh</code> (host shell command) and <code>exec</code> (execute Rexx script) commands.
    This ability may be disabled via the <a href="#SHCMDOPT">SHCMDOPT</a> statement's
    <code>NODIAG8</code> option.</i>
    <p>

    The value of <code>ECHO</code> or <code>NOECHO</code> has no effect on whether or not
    command output will be placed into the Diagnose 8 instruction's response buffer if the
    instruction requested one, nor does it cause the resulting audit trail messages from
    being placed into the response buffer either. The <code>ECHO</code> option only impacts
    what is displayed on the hardware console (and what appears in the hardcopy logfile)
    but does not otherwise impact what is placed into the instruction's response buffer.
    <p>

    The default is <code>DISABLE NOECHO</code>
    <p>

<a name="ECPSVM"></a>
<dt><code>ECPSVM &nbsp; YES &#124; <u>NO</u> &#124; LEVEL <em>nn</em> &nbsp;&nbsp; [ TRAP &#124; NOTRAP ]</code>
<dd><p>
    Specifies whether ECPS:VM (Extended Control Program Support : Virtual Machine)
    support is to be enabled.
    <p>
    If <code>YES</code> is specified, then the support level reported to the
    operating system is <code>20</code>. 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).
    <p>
    Although this feature does not affect VM Operating system products operating in
    XA, ESA or z/Architecture mode, it <i>will</i> affect VM/370 and VM/SP products
    running under VM/XA, VM/ESA or z/VM.
    <p>
    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 either. 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.
    <p>
    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.
    <p>
    This is a <i>partial</i> (but mostly complete) implementation.
    <p>
    It is however <i>not</i> a 100% complete implementation.
    <p>
    Please refer to the
    <a href="https://github.com/sdl-hercules-390/hyperion/blob/master/readme/README.ECPSVM.md">README.ECPSVM</a>
    document for more detailed information,
    including an explanation of the <code>TRAP</code> and <code>NOTRAP</code> options.
    <p>

<a name="ENGINES"></a>
<dt><code>ENGINES &nbsp; [<em>nn</em>*]<u>CP</u>&#124;IL&#124;AP&#124;IP[,...]</code>
<dd><p>
    Specifies the type of engine for each installed processor.
    The default engine type is CP.
    <p>
    <em>nn</em>* is an optional repeat count.
    Spaces are not permitted.
    <p>
    Examples:
    <p>
    <code>ENGINES CP,CP,AP,IP</code>
    <br>specifies that processor engines 0 and 1 are of type CP, engine 2 is
    type AP, and engine 3 is type IP.
    <p>
    <code>ENGINES 4*CP,2*AP,2*IP</code>
    <br>specifies that the first four processor engines (engines 0-3) are of
    type CP, the next two (engines 4-5) are of type AP, and the next two
    (engines 6-7) are of type IP.
    <p>
    The number of installed processor engines is determined by the
    <a href="#MAXCPU">MAXCPU</a> statement.
    If the ENGINES statement specifies more than MAXCPU engines, the excess
    engines are ignored. If fewer than MAXCPU engines are specified, the
    remaining engines are set to type CP.
    <p>

<a name="FACILITY"></a>
<dt><code>FACILITY &nbsp; ENABLE &#124; DISABLE &#124; QUERY &nbsp;<em>facility</em> &nbsp;<em>[archlvl]</em></code>
<dd><p>
    Specifies a particular STFL/STFLE facility to be enabled or disabled,
    or a request to query of the current settings. Use <code>QUERY ALL</code>
    to obtain a list of valid <code><em>facility</em></code> &nbsp;names
    that may be used for the given archlvl. Enter <code>help facility</code>
    for detailed <code>FACILITY</code> command/statement use.
   <p>
    Alternatively, you can also specify the actual STFL/STFLE bit number
    to be turned off or on (disabled or enabled) using the format
    <code><em>BITnn</em></code> &nbsp;where 'nn' corresponds to the exact
    STFL/STFLE facility bit you wish to be forced on or off. A popular
    one among the VM crowd is <code>ENABLE BIT44</code> to force the PFPO
    (Perform Floating-Point Operation Facility) bit on, since the facility
    is not enabled by default in SDL Hyperion version 4.1 or earlier. The
    facility is only enabled by default starting with

    <a href="https://github.com/SDL-Hercules-390/hyperion/releases/tag/Release_4.2">SDL Hyperion version 4.2</a>

    or later. Specifying <code>ENABLE BIT44</code> allows z/VM guests running
    on SDL Hyperion 4.1 or earlier to IPL.
   <p>
    The optional <code><em>archlvl</em></code> &nbsp;argument limits the enable,
    disable or query function to a specific <a href="#ARCHLVL">architecture</a>.
    It should be noted that attempts to enable or disable a facility that a given
    architecture does not support are accepted without error. The default value is
    the value that was set by a preceding <a href="#ARCHLVL">ARCHLVL</a> statement
    or the default mode if there was no preceding ARCHLVL statement.
   <p>

<a name="HERCPRIO"></a>
<dt><code>HERCPRIO &nbsp;<em>nn</em></code> &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; <i>(deprecated; unsupported)</i>
<dt><code>TODPRIO &nbsp;&nbsp;<em>nn</em></code> &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; <i>(deprecated; unsupported)</i>
<dt><code>DEVPRIO &nbsp;&nbsp;<em>nn</em></code> &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; <i>(deprecated; unsupported)</i>
<dt><code>CPUPRIO &nbsp;&nbsp;<em>nn</em></code> &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; <i>(deprecated; unsupported)</i>
<dd><p>
    The ability to define process and thread priorities has been
    <a href="hercrnot.html#4.1">removed</a> from SDL Hyperion as of version
    <a href="hercrnot.html#4.1">4.1</a>. You should remove all such statements
    from your configuration file.
    <p>

<a name="HTTPPORT"></a>
<dt><code>HTTP &nbsp; PORT &nbsp; <em>nnnn</em> [[NOAUTH] &#124; [AUTH <em>userid password</em>]]</code>
<dd><p>
    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. The server is not started until a subsequent
    <code><a href="#HTTPSTRT">HTTP START</a></code> statement is found.
    <p>
    <tt>AUTH</tt> indictates that a userid and password are required to access
    the HTTP server, whereas <tt>NOAUTH</tt> indicates that a userid and password
    are not required. The userid and password may be any valid string.
    <p>
    <i><b><u>Security Alert!</u></b> &nbsp;When <tt>AUTH</tt> is specified
    (and specifying a userid and password is thus required), one must exercise
    due diligence to prevent unauthorized access to Hercules's configuration file
    that contains those userids and passwords.
    </i>
    <p>
    <i><b><u>Security Alert!</u></b> &nbsp;The HTTP Server currently utilizes the
    insecure "http" protocol, not the more secure "https" protocol. All commands
    and responses are transmitted over the network in the clear, allowing anyone
    sniffing network traffic to see everything you do and possibly inject unauthorized
    commands of their own. Exercise caution when using the HTTP Server feature.
    </i>
    <p>

<a name="HTTPROOT"></a>
<dt><code>HTTP &nbsp; ROOT &nbsp; <em>directory</em></code>
<dd><p>
    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
    <tt>/usr/local/share/hercules/</tt>).
    <p>

<a name="HTTPSTRT"></a>
<dt><code>HTTP &nbsp; START</code>
<dd><p>
    Starts the HTTP server. (Note: The server is no longer started by default.)
    <p>

<a name="IGNORE"></a>
<dt><code>IGNORE &nbsp; INCLUDE_ERRORS</code>
<dd><p>
    Indicates that errors caused by subsequent
    <code><a href="#INCLUDE">INCLUDE</a></code> statements
    for files which do not exist should instead be ignored rather
    than causing startup to be aborted (as would otherwise normally
    occur).
    <p>

<a name="INCLUDE"></a>
<dt><code>INCLUDE &nbsp; <em>filepath</em></code>
<dd><p>
    An <code>INCLUDE</code> statement tells Hercules configuration file
    processing to treat the contents of the file specified by <em>filepath</em>
    as if its contents had appeared in the configuration file at the point
    where the <code>INCLUDE</code> statement appears.
    <p>
    Note that the included file may itself contain yet another
    <code>INCLUDE</code> statement as long as the maximum nesting depth
    (current 8) is not exceeded.
    <p>

<a name="IODELAY"></a>
<dt><code>IODELAY &nbsp; <em>usec</em></code>
<dd><p>
    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 <b>Linux/390</b> and <b>zLinux</b> <code>dasd.c</code>
    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.
    <p>
    NOTE: <a href="#OSTAILOR"><code>OSTAILOR LINUX</code></a> no longer sets
    IODELAY to 800 since the problem described above is no longer present in
    recent versions of the Linux kernel.
    <p>

<a name="LDMOD"></a>
<dt><code>LDMOD &nbsp; <em>module list</em></code>
<dd><p>
    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.
    <p>
    Multiple LDMOD statements may be used.
    <p>

<a name="LEGACYSENSEID"></a>
<dt><code>LEGACYSENSEID &nbsp; <u>OFF</u> &#124; <u>DISABLE</u> &#124; ON &#124; ENABLE</code>
<dd><p>
    Specifies whether the SENSE ID CCW (X'E4') will be honored for
    the devices that originally didn't support that feature. This
    includes (but may not be limited to) 3410 and 3420 tape drives,
    2311 and 2314 direct access storage devices,
    and 2703 communication controllers.
    <p>

    Specify <code>ON</code> or <code>ENABLE</code> if your guest
    operating system needs the Sense ID support to dynamically
    detect those devices. Note that most current operating systems
    will not detect those devices even though Sense ID is enabled
    because those devices never supported the Sense ID in the first
    place. So this mainly applies to custom built or modified versions
    of guest operating systems that are aware of this specific Hercules
    capability.
    <p>

    Because those legacy devices didn't originally support this command,
    and for compatibility reasons, the default is <code>OFF</code>
    or <code>DISABLE</code>.
    <p>

<a name="LOADPARM"></a>
<dt><code>LOADPARM &nbsp; <em>xxxxxxxx</em></code>
<dd><p>
    Specifies the <i>default</i> eight-character IPL parameter used by
    some operating systems to select system parameters.
    <p>
    The specified value is used as the <code>IPL</code> command's default
    <code>LOADPARM</code> option parameter when the <code>IPL</code>
    command is issued without the <code>LOADPARM</code> option. Regardless
    of the value specified for this setting, the value can alway be
    overridden by specifying a different value for the <code>LOADPARM</code>
    option on the <code>IPL</code> command itself. The LOADPARM configuration
    file option simply specifies a <i>default</i> value that will be used
    unless overridden with a different value on the IPL command itself.
    <p>

<a name="LOGOPT"></a>
<dt><code>LOGOPT &nbsp; <u>TIMESTAMP</u> &#124 NOTIMESTAMP &#124 DATESTAMP &#124 <u>NODATESTAMP</u> &#124 </code>
<dd><p>
    Sets logfile options. TIMESTAMP inserts a time stamp in front of
    each log message. NOTIMESTAMP logs messages without time stamps.
    Similarly, DATESTAMP and NODATESTAMP prefixes logfile messages
    with or without the current date. The current resolution of the
    stamp is one second.
    <p>
    The default is TIMESTAMP NODATESTAMP.
    <p>

<a name="LPARNAME"></a>
<dt><code>LPARNAME &nbsp; <em>name</em></code>
<dd><p>
    Specifies the LPAR name returned by DIAG X'204'.  The default is
    <code>HERCULES</code>.
    <p>

<a name="LPARNUM"></a>
<dt><code>LPARNUM &nbsp; BASIC &#124; <u>1</u> &#124; <em>xx</em></code>
<dd><p>
    Specifies the one- or two-digit hexadecimal LPAR identification
    number stored by the STIDP instruction, or BASIC.
    <p>
    If a one-digit number from <code>1</code> to <code>F</code> (hexadecimal)
    is specified, then STIDP stores a format-0 CPU ID unless a subsequent
    <a href="#CPUIDFMT"><code>CPUIDFMT 1</code></a> statement is specified.
    <p>
    If <code>0</code> or a two-digit hexadecimal number (except 10 hexadecimal)
    is specified, then STIDP stores a format-1 CPU ID. For LPARNUM <code>10</code>
    the current <a href="#CPUIDFMT"><code>CPUIDFMT</code></a> is not changed.
    <p>
    When LPARNUM is BASIC, then STIDP stores a basic-mode CPU ID (6-hexadecimal
    digit serial number when MAXCPU = 1, or a one-hexadeciaml digit CPU number
    and 5-hexadecimal digit serial number when MAXCPU > 1).
    <p>
    The LPARNUM setting will be <i>automatically changed</i>
    if needed to <code>BASIC</code> when
    <code><a href="#ARCHLVL">ARCHLVL S/370</a></code> is set (which
    also changes the <code><a href="#CPUIDFMT">CPUIDFMT</a></code>
    setting to <code>BASIC</code> too), and is automatically set
    to <code>LPARNUM 1</code> (and <code>CPUIDFMT 0</code>) if needed
    when <code><a href="#ARCHLVL">ARCHLVL z/Arch</a></code> is set.
    Refer to the <i>"Limited automatic LPARNUM updating when setting
    certain architecture modes"</i> section of the
    <a href="hercrnot.html#4.1">Release Notes</a> document for more information.
    <p>
    The default is LPARNUM 1 with a format-0 CPU ID.
    <p>

<a name="MAINSIZE"></a>
<dt><code>MAINSIZE &nbsp; <em>nnnn</em> &#124;
                          <em>nnn</em>K &#124;
                          <em>nnn</em>M &#124;
                          <em>nnn</em>G &#124;
                          <em>nnn</em>T &#124;
                          <em>nnn</em>P &#124;
                          <em>nnn</em>E</code>
<dd><p>
    Specifies the main storage size in megabytes, where
    <code><em>nnnn</em></code> &nbsp;is a decimal number. Or,
    <code><em>nnnM</em></code> &nbsp;where <code><em>M</em></code>&nbsp;
    is K - Kilobytes, M - Megabytes, G - Gigabytes, T - Terabytes,
    P - Petabytes, E - Exabytes. The default on startup is 2M.
    <p>
    For storage sizes less than 16M, sizes not on a 4K boundary are
    rounded up to the next 4K boundary. Otherwise, storage sizes not on
    a 1M boundary are rounded up to the next 1M boundary.
    <p>
    The minimum size is 64K for S/370 and 1M for ESA/390 and
    z/Arch.  A maximum of 2G may be specified for S/370 and
    ESA/390, and 16E for z/Arch.
    <p>
    <b>Notes:</b>
    <ol><p><li>
    The actual upper limit is determined by your host system's
    architecture and operating system, the guest operating system, and
    the amount of physical memory and available paging space. The total
    of mainsize and xpndsize on host systems with a 32-bit architecture
    will be limited to less than 4G; host systems with a 64-bit
    architecture will be limited to less than 16E.
    </li><p><li>
    <i>Caution:</i> using minimum storage sizes, storage sizes less than 64K
    or a size that is not a multiple of 64K for S/370, or a size
    less than 1M or is not a multiple of 1M for z/Arch is not recommended
    as it could generate error conditions which are not covered by the
    Principles of Operations.
    </li><p><li>
    Use of storage sizes greater than supported by the guest operating
    system may generate incorrect results or error conditions within the
    guest operating system.
    </li></ol>
    <p>

<a name="MANUFACTURER"></a>
<dt><code>MANUFACTURER &nbsp; <em>name</em></code>
<dd><p>
    Specifies the 1-16 character MANUFACTURER name returned the STSI instruction.
    Valid characters are 0-9 and uppercase A-Z only.
    The default is <code>HRC</code>.
    <p>

<a name="MAXCPU"></a>
<dt><code>MAXCPU &nbsp; <em>nn</em></code>
<dd><p>
    Specifies the number of installed processor engines.
    The <a href="#NUMCPU">NUMCPU</a> statement specifies the number of
    engines which will be configured online at startup time.
    All processors are CP engines unless otherwise specified by the
    <a href="#ENGINES">ENGINES</a> statement.
    <p>
    The value of MAXCPU cannot exceed the value of <code>MAX_CPU_ENGS</code>.

    If MAXCPU is not specified in the Hercules configuration file,
    then its initial value is equal to NUMCPU.

    If MAXCPU and NUMCPU are both omitted, MAXCPU is set to 1.
    <p>
    <code>MAX_CPU_ENGS</code> is a compile-time variable which sets
    an upper limit on the value of MAXCPU.
    The value of <code>MAX_CPU_ENGS</code> is displayed in the
    Build information message on the Hercules control panel at startup time.
    To change the value of <code>MAX_CPU_ENGS</code> you must rebuild
    Hercules.
    For Unix builds, specify
    <tt>./configure --enable-multi-cpu=<em>nn</em></tt>
    before performing make.
    For Windows builds, specify
    <tt>SET MAX_CPU_ENGS=<em>nn</em></tt>
    before performing nmake.
    <p>
    <code>MAX_CPU_ENGS</code> cannot exceed 64. For performance reasons,
    values above 32 are not recommended for 32-bit platforms.
    If <code>MAX_CPU_ENGS</code> is set to 1 then multiprocessing is disabled.
    See also <a href="#NUMCPU">NUMCPU</a> for a discussion of the performance
    implications of <code>MAX_CPU_ENGS</code>.
    <p>

<a name="MODEL"></a>
<dt><code>MODEL &nbsp; <em>hardware_model</em>
    [ <em>capacity_model</em> ]
    [ <em>perm_capacity_model</em> ]
    [ <em>temp_capacity_model</em> ]
    </code>
<dd><p>
    Specifies the 1-16 character MODEL names returned the STSI instruction.
    Valid characters are 0-9 and uppercase A-Z only.
    The default is <code>EMULATOR</code>.
    <p>
    If two operands are supplied, the first is the hardware model name (CPC
    ND model) and the second is the capacity model name (CPC SI model).
    If only one operand is supplied, it is used as both the hardware model
    name and the capacity model name.
    The optional third and fourth operands specify the permanent capacity
    model name and the temporary capacity model name respectively.
    <p>

<a name="MODPATH"></a>
<dt><code>MODPATH &nbsp; <em>path</em></code>
<dd><p>
    Specifies the relative or absolute path of the directory where dynamic
    modules should be loaded from. Only one directory may be specified. The
    path should be enclosed within double quotes if it contains any blanks.
    <p>
    When a modpath statement is specified, the path on the modpath statement
    is searched before the default path is searched. The system default varies
    depending on the host platform where Hercules is being run.
    <p>

<a name="MOUNTED_TAPE_REINIT"></a>
<dt><code>MOUNTED_TAPE_REINIT &nbsp; DISALLOW &#124; DISABLE &#124; <u>ALLOW</u> &#124; <u>ENABLE</u> </code>
<dd><p>
    Specifies whether reinitialization of tape drive devices (via the
    <code>devinit</code> command, in order to mount a new tape) should
    be allowed if there is already a tape mounted on the drive.
    <p>
    Specifying <code>ALLOW</code>&#124;<code>ENABLE</code> (default) indicates new tapes may
    be mounted (via <code>'devinit <i>nnnn</i> <i>new-tape-filename</i>'</code>)
    irrespective of whether or not there is already a tape mounted on the drive.
    <p>
    Specifying <code>DISALLOW</code>&#124;<code>DISABLE</code> prevents new tapes from being mounted
    if one is already mounted. When <code>DISALLOW</code> is specified
    and a tape is already mounted on the drive, it must first be unmounted
    (via the command <code>'devinit <i>nnnn</i> *'</code>) before
    the new tape can be mounted. Otherwise the devinit attempt to mount
    the new tape is rejected.
    <p>
    This option is meant as a safety mechanism to protect against
    accidentally dismounting a tape from the wrong drive as a result of
    a simple typo (thereby cancelling a potentially important tape job)
    and was added by user request.
    <p>
    Also note that for SCSI tape drives the <code>'devinit <i>nnnn</i> *'</code>
    command has no effect as the tape must be unmounted manually (since it is
    a real physical device and not one emulated via a disk file like .AWS tapes).
    <p>

<a name="NETDEV"></a>
<dt><code>NETDEV &nbsp; <em>devname</em></code>
<dd><p>
    Specifies the name (or for Windows, the IP or MAC address) of the underlying
    default host network adapter to be used for Hercules communications devices
    unless overridden on the device statement itself.
    <p>
    The default for Linux (except Apple and FreeBSD) is <code>/dev/net/tun</code>.
    The default for Apple and FreeBSD is <code>/dev/tun</code>.
    <p>
    The default for Windows is whichever host adapter that SoftDevLab's
    <a href="http://www.softdevlabs.com/ctci-win">CTCI-WIN</a> product
    returns as its "default host network adapter", which for older versions of CTCI-WIN
    (3.5.0 and earlier) is the first network adapter in the Windows host's binding
    order (which may not be desirable for some users). The <code>NETDEV</code> statement
    allows you to override this.
    <p>
    Refer to the 'Help' file included in newer versions of
    <a href="http://www.softdevlabs.com/ctci-win">CTCI-WIN</a> (version 3.6.0 or greater)
    for information regarding modifying Windows's "Adapter Binding Order" and/or defining
    a preferred CTCI-WIN default host network adapter.
    <p>
<a name="netpriv"></a>
    <center>
    <table width=95%>
      <tr><td>
        <p class="box">
        <i>
        <b>Note:</b> Hercules's networking support <u>MAY</u> require <u>privileged access</u>
        to your host's networking devices, depending on whether you use pre-configured interfaces
        or not. If you do not use pre-configured interfaces and Hercules is not started with
        <u>Administrative (root) privileges</u>, then initialization of your networking devices
        will fail and your guest's networking will not work!
        </br></br>
        If one uses pre-configured interfaces on Linux et al. however <b>(recommended!)</b>,
        then Hercules does <u>not</u> need to run as root, because the network interface it needs
        to use already exists and is already properly configured (because you already created
        and configured it yourself before you even started Hercules! So there's nothing Hercules
        needs to do before it can use it!).
        </br></br>
        If you <u>don't</u> use pre-configured interfaces however (and instead rely on Hercules
        itself to both create and configure your networking interface for you), then
        <b><u>yes</u></b>, Hercules will obviously need to be started as root in order to be able
        to do that for you.
        </br></br>
        This is why using pre-configured interfaces on *Nix et al. is so highly recommended: so
        that you <b>don't</b> need to run Hercules as root.
        </br></br>
        On Windows however, due to the way CTCI-WIN works, Administrative privileges is
        <b><u>always</u></b> required, as CTCI-WIN hooks directly into Windows's real network
        adapter's networking stack to be able to read packets directly from and write packets
        directly to the real physical adapter's networking stack.
        </i>
        </p>
      </td></tr>
    </table>
    </center>
    <p>

<a name="NUMCPU"></a>
<dt><code>NUMCPU &nbsp; <em>nn</em></code>
<dd><p>
    Specifies the number of emulated processor engines
    which will be configured online at startup time.
    NUMCPU cannot exceed the value of <a href="#MAXCPU">MAXCPU</a>.
    If NUMCPU is less than <a href="#MAXCPU">MAXCPU</a>
    then the remaining engines can be configured online later.
    The default NUMCPU value is 1. The minimum value is 0.
    <p>
    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 <tt>NUMCPU</tt> 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 <tt>MAX_CPU_ENGS</tt> to 1 at
    compile time might even produce a slight performance advantage too).
    <p>

<a name="OSTAILOR"></a>
<dt><code>OSTAILOR &nbsp; <u>DEFAULT</u> &#124; OS/390 &#124; z/OS
    &#124; VM &#124; z/VM &#124; VSE &#124; z/VSE &#124; LINUX
    &#124; OpenSolaris &#124; QUIET &#124; NULL</code>
<dd><p>
    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.
    <code>QUIET</code> <i>suppresses</i> all exception messages.
    <code>NULL</code> <i>displays</i> all exception messages.
    <p>
    <i>
    <b>Note!</b> Neither QUIET nor NULL should <u>ever</u> be used
    in normal circumstances! QUIET hides what otherwise might be important
    messages needed to diagnose incorrect Hercules and/or guest functionality.
    Only use QUIET under the guidance of Hercules product support personnel.
    Instead, please specify an OSTAILOR value that is appropriate for the guest
    operating system you intend to run under Hercules, or else let it default
    by not specifying it at all.
    </i>
    <p>
    If no <code>OSTAILOR</code> statement is specified at all, then <code><u>DEFAULT</u></code>
    is used, which suppresses only program check messages for interruption codes
    10 (segment-translation exception), 11 (page-translation exception),
    16 (trace-table exception) and 1C (space-switch event), which are considered
    to be completely normal and unremarkable for virtually all known mainframe
    operating systems.
    <p>
    Optionally prefix any value (except <code>QUIET</code> or
    <code>NULL</code>) with '+' to cause the suppressions for that
    environment to be combined (added) to those already specified,
    or with '-' to remove such suppressions (i.e. to allow them).
    <p>
    This allows you to, for example, suppress messages for both z/VM
    as well as for z/OS too (for situations where you intend to run
    z/OS as a guest under z/VM) by specifying two OSTAILOR statements
    as follows:
    <blockquote><code>
        OSTAILOR &nbsp;z/VM</br>
        OSTAILOR &nbsp;+Z/OS
    </code> </blockquote>
    <p>
    Use the "<code>pgmtrace</code>" panel command to fine tune the current settings.
    <p>

<a name="PANOPT"></a>
<dt><code>PANOPT &nbsp; <u>FULLPATH</u>&#124;NAMEONLY RATE=<u>SLOW</u>&#124;FAST&#124;<em>nnn</em> MSGCOLOR=<u>NO</u>&#124;DARK&#124;LIGHT TITLE=xxx</code>
<dd><p>
    Defines panel display options.
    <code>NAMEONLY</code> requests the extended panel screen (that displays
    the list of devices and is reached by pressing the ESC key) to display only
    the emulated device's base filename. The default is <code><u>FULLPATH</u></code>
    which displays the file's full path filename.
    <p>
    <code>RATE=<em>nnn</em></code> specifies the panel refresh rate in
    milliseconds between screen refreshes. <code>RATE=SLOW</code> is the same as 500.
    <code>RATE=FAST</code> is the same as 50. A value less than the system clock
    tick interval or greater than 5000 will be rejected. <code><u>SLOW</u></code> is the default.
    <p>
    <code>MSGCOLOR=DARK</code> displays colorized panel messages meant for
    'dark' panels (such as white text on black background) whereas
    <code>MSGCOLOR=LIGHT</code> is obviously meant for panels using dark
    text on light backgrounds. Only 'E' (error), 'W' (warning), 'D' (debug)
    and 'I' (informational) messages are colorized. Any message not detected
    as a Hercules "HHCnnnnnX" format message are not colorized. The colors
    are currently hard coded and cannot be changed. <code><u>NO</u></code> is the
    default, <i>but <code>DARK</code> or <code>LIGHT</code> (as appropriate for your system)
    is <b>strongly encouraged</b> as it makes error and warning messages more noticeable
    and less likely to be missed.</i>
    <p>
    <code>TITLE=xxx</code> defines an optional console window title-bar string
    to be used in place of the default supplied by the windowing system, and allows
    you to distinguish between different Hercules sessions (instances) running
    on the same machine. If the value contains any blanks, the entire option
    specification should be enclosed within double-quotes (e.g. <code>"TITLE=my title"</code>,
    <i>not</i> &nbsp;<code>TITLE="my title"</code> which is an error).
    <p>
    The <code>TITLE=</code> option takes effect only when the Hercules console
    is displayed on either an xterm terminal (commonly used on Unix systems)
    or in a Command Prompt window on Windows systems.
    <p>
    <b>Note:</b> neither the <code>MSGCOLOR=</code> nor the <code>TITLE=</code> option
    has any effect when Hercules is run under the control of an external GUI since
    since Hercules's console window is hidden in favor of using the external GUI's
    window instead (and the GUI is in control of its own colors). The <code>RATE=</code>
    option however, controls how often the external GUI will refresh its own window
    and other user-interface controls. Similarly, the <code>FULLPATH</code> and
    <code>NAMEONLY</code> option controls how the external GUI displays your list
    of emulated devices.
    <p>

<a name="PANRATE"></a>
<dt><code>PANRATE &nbsp; <u>SLOW</u> &#124; FAST &#124; <em>nn</em></code> &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; <i>(deprecated; use PANOPT instead)</i>
<dd><p>
    This statement has been deprecated in favor of the
    <code><a href="#PANOPT">PANOPT</a></code> statement instead.
    <p>

<a name="PANTITLE"></a>
<dt><code>PANTITLE &nbsp; <em>"title-string"</em></code> &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; <i>(deprecated; use PANOPT instead)</i>
<dd><p>
    This statement has been deprecated in favor of the
    <code><a href="#PANOPT">PANOPT</a></code> statement instead.
    <p>

<a name="PGMPRDOS"></a>
<dt><code>PGMPRDOS &nbsp; <u>RESTRICTED</u> &#124; LICENSED</code>
<dd><p>
    Specifies whether or not Hercules will run licensed program product ESA
    or z/Architecture operating systems. If <code>RESTRICTED</code> is
    specified, Hercules will stop all CPUs when a licensed program product
    operating system is detected.  Specify
    <code>LICENSED</code> 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.
    <p>

    <p class="warning">
    <b>NOTE: &nbsp;It is <u>YOUR</u> 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 their lawyers after you!</b>
    <p>

    <code>RESTRICTED</code> is the default. Specifying
    <code>LICENSED</code> will produce a message when a licensed operating
    system is detected to remind you of your responsibility to comply with
    software license terms.
    <p>

<a name="PLANT"></a>
<dt><code>PLANT &nbsp; <em>name</em></code>
<dd><p>
    Specifies the 1-4 character PLANT name returned the STSI instruction.
    Valid characters are 0-9 and uppercase A-Z only.
    The default is <code>ZZ</code>.
    <p>

<a name="SCSIMOUNT"></a>
<dt><code>SCSIMOUNT &nbsp; <u>NO</u> &#124; YES &#124; <em>nn</em></code>
<dd><p>
    Specifies whether automatic detection of SCSI tape mounts are to be
    enabled or not.
    <p>
    Specifying <code>NO</code> or 0 seconds (the default) indicates
    the option is disabled, forcing all SCSI tape mounts to be done
    manually via an appropriate <code>devinit</code> command.
    <p>
    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. Specifying <code>YES</code>&nbsp;
    is the same as specifying 5 seconds.
    <p>
    The <code>scsimount</code> panel command may also be used to display
    and/or modify this value on demand once Hercules has been started. Note
    too that the <code>scsimount</code> panel command also lists any mounts
    and/or dismounts that may still be pending on the drive, as long as
    you've defined your tape drive as a model that has an LCD "display"
    (such as a model 3480, 3490 or 3590).
    <p>
    <i>
    <b>Note:</b> &nbsp;enabling this option may cause Hercules to take
    longer to shutdown depending on the value specified for this option
    as well as how the host operating system (Windows, Linux, etc) and
    associated hardware (SCSI adapter) behaves to drive status queries
    for drives which do not have any media currently mounted on them.
    </i>
    <p>

<a name="SHCMDOPT"></a>
<dt><code>SHCMDOPT &nbsp; <u>DISABLE</u> &#124; ENABLE &nbsp; [DIAG8 &#124; <u>NODIAG8</u>]</code>
<dd><p>
    When set to <code>DISABLE</code>, the <code>sh</code> (host shell command)
    and <code>exec</code> (Rexx execute script) commands are globally disabled
    and will result in an error if entered either directly via the hardware
    console or programmatically via the <a href="#DIAG8CMD">DIAG8CMD</a> interface.
    <p>

    If the optional <code>NODIAG8</code> option is specified, then only the
    programmatic execution of commands via the the Diagnose 8 interface are disabled,
    but shell and <a href="rexx.html">Rexx commands</a> entered directly via the
    Hercules command line still work. This includes commands entered via the
    <a href="#HTTPROOT">HTTP server facility</a> as well as commands issued by
    <a href="hercinst.html#RCFILE">.rc "run command"</a> scripts too (automatically
    at startup or directly or indirectly via the <code>script</code> command).
    <p>

    <i><b><u>Security Alert</u>:</b> &nbsp;Enabling this feature has security consequences.
    When <code>ENABLE DIAG8</code> is specified it is possible for guest operating systems
    running under Hercules to issue commands directly to the host operating system.</i>
    <p>

<a name="SHRDPORT"></a>
<dt><code>SHRDPORT &nbsp; <em>nnnn</em></code>
<dd><p>
    Specifies the port number (in decimal) on which the <a href="shared.html">Shared Device server</a>
    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.<br>
    <p>

<a name="SYSEPOCH"></a>
<dt><code>SYSEPOCH &nbsp; <em>yyyy</em> [&plusmn;<em>years</em>]</code>
<dd><p>
    Specifies the base date for the TOD clock.  Use the default value
    (<code>1900</code>) for all systems except OS/360. Use <code>1960</code>
    for OS/360.  Values other than these were formerly used to offset the
    TOD clock by a number of years to move the date before the year 2000 for
    non-Y2K-compliant operating systems. This use is deprecated, and support
    will be removed in a future release; at that time, only values of
    <code>1900</code> or <code>1960</code> will be accepted. Other values
    will produce a warning message with the equivalent values to specify in
    the SYSEPOCH statement.<br>
    An optional year offset may be specified, and will be treated as though
    it had been specified on a <a href="#YROFFSET"><code>YROFFSET</code></a>
    statement.
    <p>

<a name="SYSGPORT"></a>
<dt><code>SYSGPORT &nbsp; <i><u>NO</u></i> &nbsp;<i>-or-</i> &nbsp;<i>3278</i> &nbsp;<i>-or-</i> &nbsp;<i>nnnn</i> &nbsp;<i>-or-</i> &nbsp;<i>host:port</i></code>
<dd><p>
    Specifies (typically) the port number (in decimal) to which tn3270
    and telnet clients should use to connect to a <a href="#SYSG">SYSG</a>
    console device or the value <code>NO</code>. The default is
    <code><u>NO</u></code>, meaning no separate listening socket
    will be created for SYSG console connections. If an invalid value
    is specified Hercules defaults to port number <u>3278</u>.
    See also the <a href="#CNSLPORT"><code>CNSLPORT</code></a> statement.
    <p>
    The <code>SYSGPORT</code> statement may also be specified as
    <code>host:port</code>, where <code>host</code> identifies the
    IP address of the host interface the telnet console server should
    bind to (listen for connections on). If not specified the server
    will accept connections on the port from any host interface.
    <p>
    See the <a href="telnet.html">Telnet/tn3270 Console How-To</a>
    for additional information about setting up a telnet or tn3270 client.
    <p>

<a name="TIMERINT"></a>
<dt><code>TIMERINT &nbsp; DEFAULT &#124; <em>nnnn</em></code>
<dd><p>
    Specifies the internal timers update interval, in microseconds.
    This parameter specifies how frequently Hercules's internal
    timers-update thread updates the TOD Clock, CPU Timer, and other
    architectural related clock/timer values.
    <p>
    When the z/Architecure Transactional-Execution Facility (073_TRANSACT_EXEC)
    is not installed or enabled, the minimum and default intervals are 1
    and 50 microseconds respectively, which strikes a reasonable balance
    between clock accuracy and overall host performance.
    <p>
    When the z/Architecure Transactional-Execution Facility <i><u>is</u></i> installed and
    enabled, the minimum and default intervals are 200 and 400 microseconds.
    <p>
    The maximum allowed interval is 999999 microseconds
    (one microsecond less than one second).
    <p>
    Also note that due to host system limitations and/or design, some
    hosts may round up and/or
    <a href="https://en.wikipedia.org/wiki/Timer_coalescing">coalesce</a>
    short microsecond intervals to a much longer millisecond interval instead.
    <p>
    <i><b><u>CAUTION!</u></b> &nbsp;While lower TIMERINT values <u>may</u> help increase the accuracy
    of your guest's TOD Clock and CPU Timer values, it could also have a
    <b>severe negative impact</b> on host operating system performance as well.
    You should exercise <u>extreme caution</u> when choosing your TIMERINT value
    in relationship to the actual process priority (nice value) of the
    Hercules process itself.
    </i>
    <p>

<a name="TODDRAG"></a>
<dt><code>TODDRAG &nbsp; <em>n.nn</em></code>
<dd><p>
    Specifies the TOD clock drag factor.  This parameter can be used
    to slow down or speed up the TOD clock by a factor of <em>nn</em>.
    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%.
    <p>

<a name="TRACEOPT"></a>
<dt><code>TRACEOPT &nbsp; [<u>TRADITIONAL</u> &#124; REGSFIRST &#124; NOREGS] &nbsp;[NOCH9OFLOW]</code>
<dd><p>
    Sets the Hercules instruction and device tracing option(s).
    <p>
    <code>TRADITIONAL</code> (the default), displays the instruction about
    to be executed followed by the current register values such that pressing
    the ENTER key (to execute the displayed instruction) then shows the next
    instruction to be executed followed by a display of the updated registers.
    <p>
    <code>REGSFIRST</code> displays the current register values first, followed
    by the instruction about to be executed, such that pressing the ENTER key
    (to execute the displayed instruction) then shows the newly updated
    register values (that the instruction just updated) followed by the next
    instruction about to be executed.
    <p>
    <code>NOREGS</code> suppresses the registers display altogether and shows
    just the instruction about to be executed.
    <p>
    <code>NOCH9OFLOW</code> suppresses CCW tracing of printer channel-9 overflow
    unit checks which are considered completely normal and not true device errors.
    The unit checks still occur, they are simply not traced unless CCW tracing
    is explicitly enabled on the device.
    <p>

<a name="TZOFFSET"></a>
<dt><code>TZOFFSET &nbsp; &plusmn;<em>hhmm</em></code>
<dd><p>
    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: <code>-0500</code> for US Eastern Standard
    Time, <code>-0800</code> for US Pacific Standard Time).
    For timezones east of Greenwich, specify a positive value
    (example: <code>+0100</code> for Central European Time,
    <code>+0930</code> for South Australian Time).
    <p>

<a name="XPNDSIZE"></a>
<dt><code>XPNDSIZE &nbsp; <em>nnnn</em> &#124;
                          <em>nnn</em>M &#124;
                          <em>nnn</em>G &#124;
                          <em>nnn</em>T &#124;
                          <em>nnn</em>P &#124;
                          <em>nnn</em>E</code>
<dd><p>
    Specifies the expanded storage size in megabytes, where
    <code><em>nnnn</em></code> is a decimal number. Or,
    <code><em>nnnM</em></code> &nbsp;where <code><em>M</em></code>&nbsp;
    is K - Kilobytes, M - Megabytes, G - Gigabytes, T - Terabytes,
    P - Petabytes, E - Exabytes.
    <p>
    Storage sizes not on a 1M boundary are rounded up to the next 1M
    boundary. The lower limit and default is 0.
    <p>
    <b>Notes:</b>
    <ol><p><li>
    The actual upper limit is determined by your host system's
    architecture and operating system, the guest operating system, and
    the amount of physical memory and available paging space. The total
    of mainsize and xpndsize on host systems with a 32-bit architecture
    will be limited to less than 4G; host systems with a 64-bit
    architecture will be limited to less than 16E.
    </li><p><li>
    Use of storage sizes greater than supported by the guest operating
    system may generate incorrect results or error conditions within the
    guest operating system.
    </li></ol>
    <p>

<a name="YROFFSET"></a>
<dt><code>YROFFSET &nbsp; &plusmn;<em>years</em></code>
<dd><p>
    Specifies a number of years to offset the TOD clock from the actual
    date. Positive numbers will move the clock forward in time, while
    negative numbers will move it backward. A common value for
    non-Y2K-compliant operating systems is <code>YROFFSET -28</code>, which
    has the advantage that the day of the week and the presence or absence
    of February 29 is the same as the current year. This value may not be
    specified as greater than &plusmn;142 years, the total range of the TOD
    clock. Specifying a value that causes the computed TOD clock year to be
    earlier than the value of <a href="#SYSEPOCH"><code>SYSEPOCH</code></a>
    or more than 142 years later than that value will produce unexpected
    results.
    <p>

</dl>

<p>
    A comment preceded by a &#035; sign may be appended to any system
    parameter statement.
<p>

<hr><!-- ---------------------------------------------------------------------------- -->

<a name="subs"></a>
<h3>Symbol substitutions</h3></a>
<p>
    In configuration and device statements, as well as in panel commands and OAT files,
    symbols may be substituted for text.

<h4>Syntax</h4>
<p>
    To substitute symbol <em>symbol</em> with its contents, the symbol should be enclosed
    within parenthesis and preceded by a $ sign. For example, if symbol <em>FOO</em> contains
    the text string <em>&quot;BAR&quot;</em> then <em>$(FOO)</em> will be substituted with the
    string <em>&quot;BAR&quot</em>;. Symbol names are case sensitive.

<h5>Example</h5><code><pre>
        DEFSYM  TAPEDIR  &quot;/home/hercules/tapes&quot;

        ...

        0380  3420  $(TAPEDIR)/scratch.aws

        ...</pre></code>
<p>
    In this example, device 0380 will be a 3420 loaded with the AWS tape file in <code>/home/hercules/tapes/scratch.aws</code>
<h4>Special symbols</h4>
    <h5>Device group symbols</h5>
    <p>
        When multiple devices are defined with a single device definition statement, then the symbols<P>
        <blockquote>
            <TABLE BORDER=0>
                <ul compact>
                    <TR><TD><LI>&nbsp; CUU  &nbsp; </TD><TD> &nbsp; (3 digits device number, upper case hexadecimal digits)</TD></TR>
                    <TR><TD><LI>&nbsp; CCUU &nbsp; </TD><TD> &nbsp; (4 digits device number, upper case hexadecimal digits)</TD></TR>
                    <TR><TD><LI>&nbsp; DEVN &nbsp; </TD><TD> &nbsp; (4 digits device number, upper case hexadecimal digits)</TD></TR>
                </ul>
            </TABLE>
        </blockquote>
        <p>
        are defined to contain for each device the relevant device address. For example:
        <p>
<code><pre>
    0200,0201  3340  /home/hercules/dasds/myvols.$(CUU)
</pre></code>
        <p>
        will define two 3340 packs, with device 0200 being loaded with the file myvols.200 and
        device 0201 defined with myvols.201.
    <h5>Environment variables</h5>
    <p>
        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.
    <h5>Undefined symbols</h5>
    <p>
        If a symbol is not defined by an explicit DEFSYM, is not an automatically generated symbol
        and is not an environment variable, an empty string will be substituted.
    <h4>Escaping substitution, recursion</h4>
    <p>
        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 &quot;BAR&quot;, then $$(FOO) will remain &quot;$$(FOO)&quot; while $$$(FOO)
        will become &quot;$BAR&quot;.
    <p>
        Substitution is <i>not</i> recursive (only one substitution pass is made).
    <p>
<hr><!-- ---------------------------------------------------------------------------- -->

<a name="ENHSYMINC"></a>
<h3>Enhanced symbol substitutions</h3></a>
<p>
    Enhanced symbol substitution differs from the above normal symbol substitution
    in several very important ways:
    <p>
    First, the syntax is different. Enhanced substitution symbol names are specified
    using <code>${var}</code> (dollar + brace) rather than <code>$(var)</code>
    (dollar + parenthesis).
    <p>
    Second, the enhanced syntax supports specifying a default value that is to be used
    instead whenever the name symbol is otherwise not defined. The default value is
    placed within the opening and closing braces just as the symbol name is, but
    separated from it by either a single equal sign '<code>=</code>' or a
    colon-equal-sign '<code>:=</code>'.
    <p>
    For example, specifying "<code>${DASD_PATH=dasd/}</code>" in your configuration
    file requests that the value of the "DASD_PATH" symbol or environment variable be
    substituted, or, if the variable is undefined, to use the value "<code>dasd/</code>"
    instead. If no default value is specified then an empty string is used instead.
    <p>
    Finally, enhanced symbol substitution occurs only from host defined environment
    variables and <i>not</i> from any identically named <code>DEFSYM</code> symbol
    should one exist. For example, if environment variable 'FOO' is defined with the
    value "bar", then the configuration file statement "<code>DEFSYM FOO myfoo</code>"
    followed immediately by the statement "<code>${FOO}</code>" causes the value
    "<code>bar</code>" to be substituted and <i>not</i> '<code>myfoo</code>' as might
    otherwise be believed, whereas the statement "<code>$(FOO)</code>", since it is
    a normal symbol substitution sequence <i>does</i> get replaced with "<code>myfoo</code>"
    (since that was the value defined to it via the preceding <code>DEFSYM</code>
    statement).
    <p>
    In other words each symbol substitution technique is supported completely separately
    from one another. <code>DEFSYM</code> allows one to define/undefine/use private (internally
    defined) symbols separate from the host operating system's environment variable pool,
    whereas the enhanced symbol substitution does not and instead only allows read-only
    access to the host's environment variable pool with no support for modifying an already
    defined symbol (environment variable) but a nonethless convenient means of defining
    a default value to be used should the specified host environment variable be currently
    undefined.
    <p>
    Further note that symbol names, being the names of environment variables, are subject
    to whatever case sensitivity or case insensitivity that the host operating system
    happens to enforce/allow. On Windows, environment variables are not case sensitive, whereas on other
    operating systems they may be. Thus "<code>${FOO}</code>", "<code>${foo}</code>",
    "<code>${Foo}</code>", etc, all cause the same value to be substituted on Windows,
    whereas the <code>DEFSYM</code> symbols <code>$(FOO)</code> and <code>$(foo)</code>,
    being two completely different and unique symbols, could be substituted with two
    completely different values (since <code>DEFSYM</code> <b><i>is</i></b>
    case sensitive across <i>all</i> supported platforms, <i>including</i> Windows).
    <p>
<h4>Syntax</h4>
<p>
    To substitute symbol <em>symbol</em> with the current environment variable value,
    the symbol should be enclosed within braces and preceded by a $ sign. For example,
    if an environment variable named <code>FOO</code> holds the value "BAR", then
    <code>${FOO}</code> will be substituted with the string "BAR". If the environment variable
    "FOO" is not defined then a null (empty) string is substituted instead.
    <p>
    If the string "<code>${FOO:=myfoo}</code>" is used instead, then the value "BAR" will still be
    substituted if the value "BAR" was indeed previously assigned to FOO, but will be
    substituted with the value "<code>myfoo</code>" instead if the environment variable
    FOO is currently undefined.
    <p>
    Note too that the default value is a literal
    string and no substitution is applied to it. Thus attempting to use the syntax
    "<code>${foo=${bar}}</code>" will <i>not</i> yield the expected results. It will
    <i>not</i> be substituted with the currently defined value of the "bar" environment
    variable, but rather will <i>always</i> be substituted with the literal string
    "<code>${bar</code>" followed immediately by the literal character '<code>}</code>'.
    <p>
    Symbol names (environment variable names) are not case sensitive on Windows whereas
    they might be on other host operating systems.
    <p>
<hr><!-- ---------------------------------------------------------------------------- -->

<h3>Process and Thread Priorities</h3>

<p>

<h4>Process Priorities</h4>
<P>
    For Windows, the following conversions are used for translating Unix
    process 'nice' values to Windows process priority classes:
<P>
<table frame="VOID" rules="NONE" cellpadding="0" cellspacing="0">
    <TR>
        <TH ALIGN="RIGHT" VALIGN="BASELINE" WIDTH="11%">'Nice'<br>value</TH>
        <TH ALIGN="CENTER" VALIGN="BASELINE" WIDTH="6%"><BR></TH>
        <TH ALIGN="LEFT" VALIGN="BASELINE" WIDTH="15%">Windows Process<br>Priority Class</TH>
        <TH ALIGN="LEFT" VALIGN="BASELINE" WIDTH="67%"><br>Meaning</TH>
    </TR>
    <TR> <!-- ============================================================================ -->
        <TD ALIGN="RIGHT" VALIGN="BASELINE" WIDTH="11%">&nbsp;</TD>
        <TD ALIGN="CENTER" VALIGN="BASELINE" WIDTH="6%">&nbsp;</TD>
        <TD ALIGN="LEFT" VALIGN="BASELINE" WIDTH="15%">&nbsp;</TD>
        <TD ALIGN="LEFT" VALIGN="BASELINE" WIDTH="67%">&nbsp;</TD>
    </TR>
    <TR>
        <TD ALIGN="RIGHT" VALIGN="BASELINE" WIDTH="11%">-20 to -16</TD>
        <TD ALIGN="CENTER" VALIGN="BASELINE" WIDTH="6%">&nbsp;</TD>
        <TD ALIGN="LEFT" VALIGN="BASELINE" WIDTH="15%">Real-time</TD>
        <TD ALIGN="LEFT" VALIGN="BASELINE" WIDTH="67%">
            Process that has the highest possible priority. The threads of the process
            preempt the threads of all other processes, including operating system processes
            performing important tasks. For example, a real-time process that executes for
            more than a very brief interval can cause disk caches not to flush or cause
            the mouse to be unresponsive.
        </TD>
    </TR>
    <TR> <!-- ============================================================================ -->
        <TD ALIGN="RIGHT" VALIGN="BASELINE" WIDTH="11%">&nbsp;</TD>
        <TD ALIGN="CENTER" VALIGN="BASELINE" WIDTH="6%">&nbsp;</TD>
        <TD ALIGN="LEFT" VALIGN="BASELINE" WIDTH="15%">&nbsp;</TD>
        <TD ALIGN="LEFT" VALIGN="BASELINE" WIDTH="67%">&nbsp;</TD>
    </TR>
    <TR>
        <TD ALIGN="RIGHT" VALIGN="BASELINE" WIDTH="11%">-15 to -9</TD>
        <TD ALIGN="CENTER" VALIGN="BASELINE" WIDTH="6%">&nbsp;</TD>
        <TD ALIGN="LEFT" VALIGN="BASELINE" WIDTH="15%">High</TD>
        <TD ALIGN="LEFT" VALIGN="BASELINE" WIDTH="67%">
            Process that performs time-critical tasks that must be executed immediately.
            The threads of the process preempt the threads of normal or idle priority class
            processes. An example is the Task List, which must respond quickly when called
            by the user, regardless of the load on the operating system. Use extreme care
            when using the high-priority class, because a high-priority class application
            can use nearly all available CPU time.
        </TD>
    </TR>
    <TR> <!-- ============================================================================ -->
        <TD ALIGN="RIGHT" VALIGN="BASELINE" WIDTH="11%">&nbsp;</TD>
        <TD ALIGN="CENTER" VALIGN="BASELINE" WIDTH="6%">&nbsp;</TD>
        <TD ALIGN="LEFT" VALIGN="BASELINE" WIDTH="15%">&nbsp;</TD>
        <TD ALIGN="LEFT" VALIGN="BASELINE" WIDTH="67%">&nbsp;</TD>
    </TR>
    <TR>
        <TD ALIGN="RIGHT" VALIGN="BASELINE" WIDTH="11%">-8 to -1</TD>
        <TD ALIGN="CENTER" VALIGN="BASELINE" WIDTH="6%">&nbsp;</TD>
        <TD ALIGN="LEFT" VALIGN="BASELINE" WIDTH="15%">Above Normal</TD>
        <TD ALIGN="LEFT" VALIGN="BASELINE" WIDTH="67%">
            Process that has priority above the Normal class but below the High class.
        </TD>
    </TR>
    <TR> <!-- ============================================================================ -->
        <TD ALIGN="RIGHT" VALIGN="BASELINE" WIDTH="11%">&nbsp;</TD>
        <TD ALIGN="CENTER" VALIGN="BASELINE" WIDTH="6%">&nbsp;</TD>
        <TD ALIGN="LEFT" VALIGN="BASELINE" WIDTH="15%">&nbsp;</TD>
        <TD ALIGN="LEFT" VALIGN="BASELINE" WIDTH="67%">&nbsp;</TD>
    </TR>
    <TR>
        <TD ALIGN="RIGHT" VALIGN="BASELINE" WIDTH="11%">0 to +7</TD>
        <TD ALIGN="CENTER" VALIGN="BASELINE" WIDTH="6%">&nbsp;</TD>
        <TD ALIGN="LEFT" VALIGN="BASELINE" WIDTH="15%">Normal</TD>
        <TD ALIGN="LEFT" VALIGN="BASELINE" WIDTH="67%">
            Process with no special scheduling needs.
        </TD>
    </TR>
    <TR> <!-- ============================================================================ -->
        <TD ALIGN="RIGHT" VALIGN="BASELINE" WIDTH="11%">&nbsp;</TD>
        <TD ALIGN="CENTER" VALIGN="BASELINE" WIDTH="6%">&nbsp;</TD>
        <TD ALIGN="LEFT" VALIGN="BASELINE" WIDTH="15%">&nbsp;</TD>
        <TD ALIGN="LEFT" VALIGN="BASELINE" WIDTH="67%">&nbsp;</TD>
    </TR>
    <TR>
        <TD ALIGN="RIGHT" VALIGN="BASELINE" WIDTH="11%">+8 to +14</TD>
        <TD ALIGN="CENTER" VALIGN="BASELINE" WIDTH="6%">&nbsp;</TD>
        <TD ALIGN="LEFT" VALIGN="BASELINE" WIDTH="15%">Below Normal</TD>
        <TD ALIGN="LEFT" VALIGN="BASELINE" WIDTH="67%">
            Process that has priority above the Idle class but below the Normal class.
        </TD>
    </TR>
    <TR> <!-- ============================================================================ -->
        <TD ALIGN="RIGHT" VALIGN="BASELINE" WIDTH="11%">&nbsp;</TD>
        <TD ALIGN="CENTER" VALIGN="BASELINE" WIDTH="6%">&nbsp;</TD>
        <TD ALIGN="LEFT" VALIGN="BASELINE" WIDTH="15%">&nbsp;</TD>
        <TD ALIGN="LEFT" VALIGN="BASELINE" WIDTH="67%">&nbsp;</TD>
    </TR>
    <TR>
        <TD ALIGN="RIGHT" VALIGN="BASELINE" WIDTH="11%">+15 to +19</TD>
        <TD ALIGN="CENTER" VALIGN="BASELINE" WIDTH="6%">&nbsp;</TD>
        <TD ALIGN="LEFT" VALIGN="BASELINE" WIDTH="15%">Idle</TD>
        <TD ALIGN="LEFT" VALIGN="BASELINE" WIDTH="67%">
            Process whose threads run only when the system is idle. The threads of the
            process are preempted by the threads of any process running in a higher priority
            class. An example is a screen saver. The idle-priority class is inherited by
            child processes.
        </TD>
    </TR>
</TABLE>

<p>
<blockquote>
    <i>
    <b>Caution!</b>&nbsp;
    A high process priority (or low 'nice' value) could have a impact on how
    Hercules's internal thread priorities are interpreted, thereby impacting
    the overall performance of your host system.
    </i>
</blockquote>

<p>

<h4>Thread Priorities</h4>
<P>
    The following are the currently assigned internal relative thread priorities
    for Hercules:
<P>

<table frame="VOID" rules="NONE" cellpadding="0" cellspacing="0">
    <TR>
        <TH ALIGN="RIGHT" VALIGN="BASELINE" WIDTH="11%">Relative<br>priority</TH>
        <TH ALIGN="CENTER" VALIGN="BASELINE" WIDTH="6%"><BR></TH>
        <TH ALIGN="LEFT" VALIGN="BASELINE" WIDTH="15%">Thread<br>Type</TH>
        <TH ALIGN="LEFT" VALIGN="BASELINE" WIDTH="67%"><br>Description</TH>
    </TR>
    <TR> <!-- ============================================================================ -->
        <TD ALIGN="RIGHT" VALIGN="BASELINE" WIDTH="11%">&nbsp;</TD>
        <TD ALIGN="CENTER" VALIGN="BASELINE" WIDTH="6%">&nbsp;</TD>
        <TD ALIGN="LEFT" VALIGN="BASELINE" WIDTH="15%">&nbsp;</TD>
        <TD ALIGN="LEFT" VALIGN="BASELINE" WIDTH="67%">&nbsp;</TD>
    </TR>
    <TR>
        <TD ALIGN="RIGHT" VALIGN="BASELINE" WIDTH="11%">1</TD>
        <TD ALIGN="CENTER" VALIGN="BASELINE" WIDTH="6%">&nbsp;</TD>
        <TD ALIGN="LEFT" VALIGN="BASELINE" WIDTH="15%">(watchdog)</TD>
        <TD ALIGN="LEFT" VALIGN="BASELINE" WIDTH="67%">
            The "watch dog" thread is the internal Hercules thread that monitors
            all CPU threads for a  malfunctioning CPU (i.e. one that, due to a bug,
            has stopped executing instructions). The watch dog thread is always
            set to a relative priority one less than the priority assigned to
            the CPU threads.
        </TD>
    </TR>
    <TR> <!-- ============================================================================ -->
        <TD ALIGN="RIGHT" VALIGN="BASELINE" WIDTH="11%">&nbsp;</TD>
        <TD ALIGN="CENTER" VALIGN="BASELINE" WIDTH="6%">&nbsp;</TD>
        <TD ALIGN="LEFT" VALIGN="BASELINE" WIDTH="15%">&nbsp;</TD>
        <TD ALIGN="LEFT" VALIGN="BASELINE" WIDTH="67%">&nbsp;</TD>
    </TR>
    <TR>
        <TD ALIGN="RIGHT" VALIGN="BASELINE" WIDTH="11%">2</TD>
        <TD ALIGN="CENTER" VALIGN="BASELINE" WIDTH="6%">&nbsp;</TD>
        <TD ALIGN="LEFT" VALIGN="BASELINE" WIDTH="15%">CPU</TD>
        <TD ALIGN="LEFT" VALIGN="BASELINE" WIDTH="67%">
            The CPU threads are those within Hercules that actually execute the emulated
            System/370, ESA/390, or z/Architecture instructions. There is one CPU thread
            for each defined ENGINE. Except for the watch dog thread, CPU threads are always
            assigned the lowest relative priority of any thread within Hercules. This
            allows, for example, I/O requests to be scheduled and completed
            in favour of CPU cycles being burned.
        </TD>
    </TR>
    <TR> <!-- ============================================================================ -->
        <TD ALIGN="RIGHT" VALIGN="BASELINE" WIDTH="11%">&nbsp;</TD>
        <TD ALIGN="CENTER" VALIGN="BASELINE" WIDTH="6%">&nbsp;</TD>
        <TD ALIGN="LEFT" VALIGN="BASELINE" WIDTH="15%">&nbsp;</TD>
        <TD ALIGN="LEFT" VALIGN="BASELINE" WIDTH="67%">&nbsp;</TD>
    </TR>
    <TR>
        <TD ALIGN="RIGHT" VALIGN="BASELINE" WIDTH="11%">3</TD>
        <TD ALIGN="CENTER" VALIGN="BASELINE" WIDTH="6%">&nbsp;</TD>
        <TD ALIGN="LEFT" VALIGN="BASELINE" WIDTH="15%">Device</TD>
        <TD ALIGN="LEFT" VALIGN="BASELINE" WIDTH="67%">
            Device threads within Hercules manage the I/O requests to emulated devices.
            Assigning the internal relative priority of device threads to be higher than
            that of the CPU threads ensures no compute-bound CPU thread impacts Hercules's
            ability to start and complete its I/O requests to its emulated devices.
        </TD>
    </TR>
    <TR> <!-- ============================================================================ -->
        <TD ALIGN="RIGHT" VALIGN="BASELINE" WIDTH="11%">&nbsp;</TD>
        <TD ALIGN="CENTER" VALIGN="BASELINE" WIDTH="6%">&nbsp;</TD>
        <TD ALIGN="LEFT" VALIGN="BASELINE" WIDTH="15%">&nbsp;</TD>
        <TD ALIGN="LEFT" VALIGN="BASELINE" WIDTH="67%">&nbsp;</TD>
    </TR>
    <TR>
        <TD ALIGN="RIGHT" VALIGN="BASELINE" WIDTH="11%">4</TD>
        <TD ALIGN="CENTER" VALIGN="BASELINE" WIDTH="6%">&nbsp;</TD>
        <TD ALIGN="LEFT" VALIGN="BASELINE" WIDTH="15%">Server</TD>
        <TD ALIGN="LEFT" VALIGN="BASELINE" WIDTH="67%">
            Server threads are those threads that provide a service to either the user or
            to other threads internal to Hercules. Threads that monitor for incoming
            emulated display terminal connection requests for example (or the internal
            logger thread that manages the passing of messages between threads) are two
            examples of server threads. Such threads must react to connection requests
            and/or internal messages quickly since other threads are waiting for them
            to complete their task before they themselves can proceed.
        </TD>
    </TR>
    <TR> <!-- ============================================================================ -->
        <TD ALIGN="RIGHT" VALIGN="BASELINE" WIDTH="11%">&nbsp;</TD>
        <TD ALIGN="CENTER" VALIGN="BASELINE" WIDTH="6%">&nbsp;</TD>
        <TD ALIGN="LEFT" VALIGN="BASELINE" WIDTH="15%">&nbsp;</TD>
        <TD ALIGN="LEFT" VALIGN="BASELINE" WIDTH="67%">&nbsp;</TD>
    </TR>
    <TR>
        <TD ALIGN="RIGHT" VALIGN="BASELINE" WIDTH="11%">5</TD>
        <TD ALIGN="CENTER" VALIGN="BASELINE" WIDTH="6%">&nbsp;</TD>
        <TD ALIGN="LEFT" VALIGN="BASELINE" WIDTH="15%">Panel</TD>
        <TD ALIGN="LEFT" VALIGN="BASELINE" WIDTH="67%">
            The main Hercules thread is the one that reads commands from the keyboard and
            displays messages on the screen. Except for the TOD Clock and Timer thread, it
            should normally be the highest priority of any thread within Hercules.
        </TD>
    </TR>
    <TR> <!-- ============================================================================ -->
        <TD ALIGN="RIGHT" VALIGN="BASELINE" WIDTH="11%">&nbsp;</TD>
        <TD ALIGN="CENTER" VALIGN="BASELINE" WIDTH="6%">&nbsp;</TD>
        <TD ALIGN="LEFT" VALIGN="BASELINE" WIDTH="15%">&nbsp;</TD>
        <TD ALIGN="LEFT" VALIGN="BASELINE" WIDTH="67%">&nbsp;</TD>
    </TR>
    <TR>
        <TD ALIGN="RIGHT" VALIGN="BASELINE" WIDTH="11%">6</TD>
        <TD ALIGN="CENTER" VALIGN="BASELINE" WIDTH="6%">&nbsp;</TD>
        <TD ALIGN="LEFT" VALIGN="BASELINE" WIDTH="15%">(unused)</TD>
        <TD ALIGN="LEFT" VALIGN="BASELINE" WIDTH="67%">
            ---
        </TD>
    </TR>
    <TR> <!-- ============================================================================ -->
        <TD ALIGN="RIGHT" VALIGN="BASELINE" WIDTH="11%">&nbsp;</TD>
        <TD ALIGN="CENTER" VALIGN="BASELINE" WIDTH="6%">&nbsp;</TD>
        <TD ALIGN="LEFT" VALIGN="BASELINE" WIDTH="15%">&nbsp;</TD>
        <TD ALIGN="LEFT" VALIGN="BASELINE" WIDTH="67%">&nbsp;</TD>
    </TR>
    <TR>
        <TD ALIGN="RIGHT" VALIGN="BASELINE" WIDTH="11%">7</TD>
        <TD ALIGN="CENTER" VALIGN="BASELINE" WIDTH="6%">&nbsp;</TD>
        <TD ALIGN="LEFT" VALIGN="BASELINE" WIDTH="15%">Timer</TD>
        <TD ALIGN="LEFT" VALIGN="BASELINE" WIDTH="67%">
            TOD Clock and Timer thread is the thread which manages the internal emulated
            TOD Clock and CPU Timer components of your emulated mainframe. In order to
            ensure accurate time of day and elapsed time and/or CPU time measurement, it
            should always be the very highest priority thread within Hercules.
        </TD>
    </TR>
</TABLE>

<p>
<blockquote>
    <i>
    <b>Caution:</b>&nbsp;
    Hercules's internal thread priorities could be interpreted differently
    based on its process priority (or 'nice' value), thereby impacting the
    overall performance of your host system.
    </i>
</blockquote>

<p>

<hr><!-- ---------------------------------------------------------------------------- -->

<a name="device_stmts"></a>
<h3>Device statements</h3>

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

    <blockquote>
    <code><em>devnum(s) &nbsp; devtype</em> &nbsp; [ <em>arguments</em> ] &nbsp; [ <em># comments...</em> ] </code>
    </blockquote>
    <p>

    where the generic syntax for device numbers is &nbsp;
    <code>[n:]CCUU[,CCUU][-CCUU][.nn][...]</code> &nbsp;
    as explained below:

<blockquote>

<dl> <!-- begin Device statements -->
<a name="devnums"></a>

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

    All devices defined when <em>devnums</em> 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.
    <p>

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

    <p />
    The 4 special subtitution symbols CUU, CCUU, cuu and ccuu are also defined for each
    device in a device group. See <a href="#subs">substitutions</a> for details.
    <p>

<dt><code><em>devnum</em></code>
<dd><p>
    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.
    <p>
<dt><code><em>Channel Set / Logical Channel Subsystem</em></code>
<dd><p>
    An optional Channel Set or Logical Channel Subsystem Identification can be
    specified for a device number or group of devices. The Identification
    number is specified at the beginning of the definition, followed by a ':'
    character. For example :<p>
    1:0400-040F 3270<p>
    defines 3270 devices 400 to 40F to be on S/370 Channel Set 1 or on S/390
    or z/Architecture Logical Channel Subsystem # 1.<p>
    Since each Logical Channel Subsystem defines its own device numbering space,
    care should be taken in S/370 mode as to define a coherent set of device
    numbers.<p>
    Not all S/390 or z/Architecture operating systems support Multiple Logical
    Channel Subsystems (this feature was introduced with the z9-109).<p>
    If no Channel Set or Logical Channel Subsystem Identification is specified,
    then it is assumed to be 0.
    <p>

<dt><code><em>devtype</em></code>
<dd><p>
    is the device type.  Valid device types are shown in the
    <a href="#device_types_table">table</a> just below.
    <p>

<dt><code><em>arguments</em></code>
<dd><p>
    is a list of parameters whose meaning depends on the device type.
    The arguments required for each class of device are shown further
    below.
    <p>

<dt><code><em># comments...</em></code>
<dd><p>
    A comment preceded by a &#035; sign may be appended to any device
    definition statement.
    <p>

</dl> <!-- end Device statements -->

</blockquote>

<p><br>

<a name="device_types_table"></a>

    <table width=85%>
    <tr>

        <td width=15%>
        &nbsp;
        </td>

        <td>

            <table border=1 cellpadding=8>

            <tr>
                <th colspan=3><br><big>Supported Device Types</big><p></th>
            </tr>

            <tr><th>Device type</th>
                <th>Description</th>
                <th>Emulated by</th>
            </tr>

            <tr><td>3270, 3287</td>
                <td><a href="#loc3270">Local non-SNA 3270 display or printer</a></td>
                <td>TN3270 client connection</td>
            </tr>

            <tr><td>SYSG</td>
                <td><a href="#SYSG">Integrated 3270 console</a></td>
                <td>TN3270 client connection</td>
            </tr>

            <tr><td>1052, 3215</td>
                <td><a href="#conprkb">Console printer-keyboards</a></td>
                <td>Telnet client connection</td>
            </tr>

            <tr><td>1052-C, 3215-C</td>
                <td><a href="#consysc">Integrated console printer-keyboards</a></td>
                <td>Integrated on Hercules console</td>
            </tr>

            <tr><td>1442, 2501, 3505</td>
                <td><a href="#cardrdr">Card readers</a></td>
                <td>Disk file(s) (ASCII or EBCDIC)</td>
            </tr>

            <tr><td>3525</td>
                <td><a href="#cardpch">Card punch</a></td>
                <td>Disk file (ASCII or EBCDIC)</td>
            </tr>

            <tr><td>1403, 3203, 3211</td>
                <td><a href="#printer">Line printers</a></td>
                <td>Disk file (ASCII)</td>
            </tr>

            <tr><td>3410, 3420, 3422, 3430, 3480, 3490, 3590, 9347, 8809</td>
                <td><a href="#tapedev">Tape drives</a></td>
                <td>Disk file, CDROM, or SCSI tape</td>
            </tr>


            <tr>
                <td>
                        &nbsp; &nbsp;<a href="#COMM"><i>many</i></a>
                </td>
                <td>
                        Communication and Channel-to-Channel devices
                </td>
                <td>
                        &nbsp; &nbsp; &nbsp; <a href="#COMM"><i>many</i></a>
                </td>
            </tr>

            <tr>
                <td>
                        (( <a href="#QETH">OSA</a> ))
                </td>
                <td>
                            OSA Express adapter operating on QDIO mode.
                            Both layer-2 and layer-3 modes are supported.
                </td>
                <td>
                        <a href="#QETH">"QETH" (OSA/QDIO Ethernet Adapter)
                        <br>Tun/Tap Driver</a>
                </td>
            </tr>

            <tr>
                <td>
                        (( <a href="#LCS">LCS</a> ))
                </td>
                <td>
                            IBM 8232 LCS device, LCS3172 driver of a P/390,
                            IBM 2216 router, IBM 3172 running ICP.
                </td>
                <td>
                        <a href="#LCS">"LCS" (LAN Channel Station)
                        <br>Tun/Tap Driver</a>
                </td>
            </tr>

            <tr>
                <td>
                        (( <a href="#CTCI">CTCI</a> ))
                </td>
                <td>
                        Channel-to-Channel link to host TCP/IP stack
                </td>
                <td>
                        <a href="#CTCI">"CTCI" Tun/Tap Driver</a>
                </td>
            </tr>

            <tr>
                <td>
                        (( <a href="#CTCE">CTCE</a> ))
                </td>
                <td>
                        Enhanced Channel-to-Channel Emulation<br>
                        via TCP connection <i>(true 3088 CTCA)</i>
                </td>
                <td>
                        <a href="#CTCE">"CTCE" driver</a>
                </td>
            </tr>

            <tr>
                <td>
                        (( <a href="#PTP">PTP</a> ))
                </td>
                <td>
                        MPCPTP/MPCPTP6 Channel to Channel link
                </td>
                <td>
                        <a href="#PTP">"PTP" Tun/Tap Driver</a>
                </td>
            </tr>


            <tr><td>3310, 3370, 9332, 9335, 9336, 0671</td>
                <td><a href="#fbadasd">FBA direct access storage devices</a></td>
                <td>Disk file</td>
            </tr>

            <tr><td>2305, 2311, 2314, 3330, 3340, 3350, 3375, 3380, 3390, 9345</td>
                <td><a href="#ckddasd">CKD direct access storage devices</a></td>
                <td>Disk file</td>
            </tr>

            <tr><td>2703</td>
                <td><a href="#2703">Communication Line</a>, <a href="#2703">Remote Teletype</a>, etc.</td>
                <td>TCP Socket</td>
            </tr>

            </table>

        </td>

    </tr>
    </table>

<p><br>


<h4>Arguments required for each device type</h4>

<dl> <!-- begin Arguments for each device type -->

<p>
<a name="3270"></a>
<a name="loc3270"></a>
<dt><em>Local non-SNA 3270 devices</em>
<dd><p>
    There are no required arguments for this particular device type, but
    there are however several optional arguments which are discussed below.
    <p>

    To use this device, a tn3270 client must connect to the host machine
    via the port number specified on the <a href="#CNSLPORT">CNSLPORT</a>
    statement. A valid tn3270 device type, such as IBM-3278, must be used.
    See the <a href="telnet.html">Telnet/tn3270 Console How-To</a>
    for additional information about setting up a tn3270 client.
    <p>

    If your tn3270 client software allows you to specify a device type suffix
    (e.g. <code>IBM-3278@001F</code> ), 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.
    <p>

    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 <i>might</i> be eligible is
    <i>not</i> automatically selected instead.
    <p>

    Optional arguments:
    <p>

    <dl>
    <a name="loc3270group"></a>
    <dt><code><em>groupname</em></code>
    <dd><p>
        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. <code>IBM-3278@GROUPNAME</code> ) 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 <i>not</i> have a group name specified on
        their device statements. The terminal group name, if specified, should
        be 1 to 8 alphanumeric characters, the first character being alphabetic,
        and it should <i>not</i> be a hexadecimal number. Upper and lower case
        letters in the group name are considered to be equivalent.
        <p>

    <a name="loc3270ipaddr"></a>
    <dt><code><em>ipaddr</em> [ <em>mask</em> ]</code>
    <dd><p>
        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.
        <p>

        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 the next available device, if
        any, for which the client is eligible to connect (if any) is selected instead.
        <p>

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

        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 <i>ahead of</i> (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.
        <p>

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

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

    </dl>

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

<hr width="50%"><p>

<a name="SYSG"></a>
<dt><em>Integrated 3270 console device</em> &nbsp; (SYSG)
<dd><p>

    The integrated 3270 (SYSG) console is similar to a <a href="#loc3270">local non-SNA
    3270</a> device, except that it is not addressed by subchannel number and it is
    supported only by certain system control programs. The SYSG console is defined
    like a 3270 device except that the device number is ignored (but is usually specified
    as 0000) and the device type is specified as "SYSG". Only one SYSG console device
    may be defined in a configuration.
    <p>

    Use tn3270 client software to connect to the SYSG console device via the port number
    specified on the <a href="#SYSGPORT">SYSGPORT</a> statement if specified <i>(or to
    the port number specified on the <a href="#CNSLPORT">CNSLPORT</a> statement if not
    specified)</i>, just as you would connect to a regular local non-SNA 3270 device.
    See the <a href="telnet.html">Telnet/tn3270 Console How-To</a>
    for additional information about setting up a tn3270 client.
    <p>

    The SYSG console device configuration statement recognizes optional arguments
    which specify <a href="#loc3270group">group name</a> and
    <a href="#loc3270ipaddr">IP address</a> in the same way as previously described
    for a <a href="#loc3270">local non-SNA 3270</a> devices. When the
    <a href="#SYSGPORT">SYSGPORT</a> statement is not specified, these optional
    arguments provide an alternate way to ensure that a given tn3270 client
    can connect directly to the SYSG device. If the group name and IP address
    arguments are not specified (and no <a href="#SYSGPORT">SYSGPORT</a> statement
    is specified), then the SYSG console is considered to be a member of the general
    pool of devices eligible for connection by any incoming tn3270 client.
    <p>

<hr width="50%"><p>

<a name="consysc"></a>
<dt><em>Integrated Console printer-keyboard devices</em> &nbsp; (-C)
<dd><p>

    There are two optional arguments: the command prefix argument and the
    optional <code>noprompt</code> argument.
    <p>
    Since integrated console printer-keyboard devices use the Hercules HMC
    panel (Hardware Management Console) for all input and output, the command
    prefix is needed so Hercules can distinguish between input meant for the
    device and normal Hercules panel command input.
    <p>
    All integrated console devices must use a different command prefix and
    must not be a subset or superset of any other device's command prefix.
    If one is not specified then the next available default is chosen from
    the following list:
    <p>
    <pre>
        Hex     Glyph    Description

        0x2F      /       slash (default)
        0x60      `       backtick
        0x3D      =       equals
        0x7E      ~       tilde
        0x40      @       at sign
        0x24      $       dollar
        0x25      %       percent
        0x5E      ^       caret
        0x26      &       ampersand
        0x5F      _       underline
        0x3A      :       colon
        0x3F      ?       question
        0x30      0       zero
        0x31      1       one
        0x32      2       two
        0x33      3       three
        0x34      4       four
        0x35      5       five
        0x36      6       six
        0x37      7       seven
        0x38      8       eight
        0x39      9       nine</pre>

    <p>
    If your command prefix was the '/' slash character for example, then to send
    a logon command to a 1052-C or 3215-C device, you would enter "/logon" on the
    Hercules console. Or, if your command prefix was "foo=" then you would enter
    "foo=logon", etc.
    <p>
    When your guest operating system writes a message to an integrated console
    printer-keyboard device, the message displayed on the Hercules console is
    always prefixed with the device's command prefix string so you can distinguish
    it from messages written by other integrated console devices and/or Hercules
    itself.
    <p>
    The second optional argument for integrated console printer-keyboard devices
    is the <code>noprompt</code> keyword. If not specified, then whenever the
    system is awaiting input on that device, the prompting message "Enter input
    for console device nnnn" is displayed on the Hercules console. The
    <code>noprompt</code> option suppresses this prompting message.
    <p>

<hr width="50%"><p>

<a name="conprkb"></a>
<dt><em>Console printer-keyboard devices</em>
<dd><p>

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

    To use this device, a telnet client must connect to the host machine
    via the port number specified on the <a href="#CNSLPORT">CNSLPORT</a> statement.
    See the <a href="telnet.html">Telnet/tn3270 Console How-To</a>
    for additional information about setting up a telnet or tn3270 client.
    <p>

    If your telnet client software allows you to specify a device type suffix
    (for example: <code>ansi@0009</code> ), 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.
    <p>

    An optional <code>noprompt</code> 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.
    <p>

    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
    <a href="#loc3270">Local non-SNA 3270 devices</a> section with the exception
    that the "noprompt" option, if specified, must precede the other arguments.
    <p>

<hr width="50%"><p>

<a name="1442"></a>
<a name="3505"></a>
<a name="cardrdr"></a>
<dt><em>Card reader devices</em>
<dd><p>

    The argument specifies a list of file names containing card images.
    Additional arguments may be specified after the file names:
    <p>

    <dl>
    <dt><code>sockdev</code>
    <dd><p>
        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: <code>port</code> or <code>host:port</code>
        or <code>sockpath/sockname</code>.  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 <a href="hercrdr.html">Hercules Socket Reader</a>
        page for more details.
        <p>

    <dt><code>eof</code>
    <dd><p>
        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
        <code>intrq</code> option.
        <p>

    <dt><code>intrq</code>
    <dd><p>
        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 <code>eof</code>
        option.
        <p>

    <dt><code>multifile</code>
    <dd><p>
        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.
        <p>

    <dt><code>ebcdic</code>
    <dd><p>
        Specifies that the file contains fixed length 80-byte EBCDIC
        records with no line-end delimiters.
        <p>

    <dt><code>ascii</code>
    <dd><p>
        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.
        <p>

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

    <dt><code>trunc</code>
    <dd><p>
        Specifies, for ASCII files, that lines longer than 80
        characters are truncated instead of producing a unit check
        error.
        <p>

    <dt><code>autopad</code>
    <dd><p>
        Specifies, for EBCDIC files, that the file is automatically
        padded to a multiple of 80 bytes if necessary.
        <p>

    </dl>
    <p>

<hr width="50%"><p>

<a name="3525"></a>
<a name="cardpch"></a>
<dt><em>Card punch devices</em>
<dd><p>
    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:
    <p>

    <dl>
    <dt><code>append</code>
    <dd><p>
        Specifies that the output file, if it already exists, will
        not be cleared to zero bytes when it is opened. Instead,
        output will be appended to the end of the existing data.
        If the <code>noclear</code> argument is not specified, then
        any previous contents of the file is destroyed when the file
        is opened (i.e. the file is set to empty (truncated to zero
        bytes) as soon as it is opened).
        <p>

    <dt><code>ascii</code>
    <dd><p>
        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.
        This is the opposite of the <code>ebcdic</code> option.
        <p>

    <dt><code>crlf</code>
    <dd><p>
        Specifies, for ASCII files, that carriage return line feed
        sequences are written at the end of each line.
        If the <code>crlf</code> argument is not specified, then
        line-feeds only are written at the end of each line.
        <p>

    <dt><code>ebcdic</code>
    <dd><p>
        Specifies the file is written as fixed length 80-byte EBCDIC
        records with no line-end delimiters (the opposite of the
        <code>ascii</code> option). This is the default.
        <p>

    <dt><code>noclear</code> &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; <i>(deprecated)</i>
    <dd><p>
        This option is deprecated and will be removed in a future
        release.  Please use the more aptly named <code>append</code>
        option instead.
        <p>

    <dt><code>sockdev</code>
    <dd><p>
        Indicates the card punch 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: <code>port</code> or <code>host:port</code>.
        The device then accepts
        remote connections on the given TCP/IP port,
        and writes data to the socket instead of to a device
        file. This allows automatic remote spooling of card punch
        data. The sockdev option is mutually exclusive with the
        <code>crlf</code> and <code>append</code> options.
        <p>

    </dl>
    <p>

<hr width="50%"><p>

<a name="1403"></a>
<a name="printer"></a>
<dt><em>Line printer devices</em>
<dd><p>
    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.

    <p>

    Additional arguments may be specified after the file name:
    <p>

    <dl>
    <dt><code>append</code>
    <dd><p>
        Specifies that the output file, if it already exists, will
        not be cleared to zero bytes when it is opened. Instead,
        output will be appended to the end of the existing data.
        If the <code>append</code> argument is not specified, then
        any previous contents of the file is destroyed when the file
        is opened (i.e. the file is set to empty (truncated to zero
        bytes) as soon as it is opened).
        <p>

    <dt><code>cctape= &nbsp;<i>(lll=cc[,lll=cc]...)</i> | <i>name</i></code>
    <dd><p>
        This option defines the carriage control tape to use for this printer.
        It is only valid for 1403 printer devices.
        <p>
        The option can be specified as either a series of <code>lll=cc</code>
        values surrounded by parentheses where <code>lll</code> identifies
        the carriage control tape's line number (<code>1-255</code>) and
        <code>cc</code> indicates the channel punch for that line
        (<code>1-12</code>), or as a predefined carriage control
        tape <code>name</code>.
        <p>
        More than one channel punch may be specified for a line by either
        specifying the desired list of channel punches for that line
        within parentheses or by simply specifying the same line number again
        in your list but with a different channel number each time.
        <p>
        The <code>name</code> format specifies the name of a predefined
        carriage control tape. Valid predefined cctape names are:
        <code>legacy</code>, <code>fcb2std2</code> or <code>fcb2id1</code>.
        The default if not specified is <code>legacy</code>.

        <blockquote>
            <code><b><u>legacy</u></b>: &nbsp; &nbsp; cctape=(1=1,7=2,13=3,19=4,25=5,31=6,37=7,43=8,63=9,49=10,55=11,61=12)</code>
            <br>
            <code>fcb2std2: &nbsp; cctape=(1=1,7=2,13=3,19=4,25=5,31=6,37=7,43=8,49=9,55=10,61=11,63=12)</code>
            <br>
            <code>fcb2id1: &nbsp; &nbsp;cctape=(1=1,8=2,15=3,22=4,29=5,36=6,43=7,50=8,57=9,64=10,71=11,78=12)</code>
        </blockquote>

        Note that the <u>lines per page</u> value is not supported by the
        <code>cctape</code> option. Instead, you must specify your desired
        lines per page value separately via the <code>lpp</code> option.
        <p>

    <dt><code>crlf</code>
    <dd><p>
        Specifies that carriage return line feed sequences should be written
        at the end of each line. If the <code>crlf</code> argument is not specified
        then the default behavior is to only write line-feeds at the end of each line.
        <p>

    <dt><code>fcb= &nbsp;<i>ppnnnnnnnnnnnnnnnnnnnnnnnn</i> | <i>cc:lll[,cc:lll]...</i> | <i>name</i></code>
    <dd><p>
        This option is only valid for 3203 or 3211 printer devices.
        It specifies an initial FCB image to use for this printer.
        <p>
        This option supports three different formats: old, new and name.
        <p>
        The old format argument must be exactly 26 digits long, and consist
        of digits from 0 to 9. The first pair of digits (<code>pp</code>) specifies
        the number of lines on a printed page (01-99). It is followed by 12 pairs
        of digits (<code>nn</code>) which specify the line number on the page
        (<code>00-99</code>) corresponding to each of the 12 possible FCB channels.
        Specify the line number as <code>00</code> for those channels you wish to
        leave undefined.
        <p>
        The new format is specified as a series of semicolon-delimited channel and
        line number pairs (<code>cc:lll</code>), each successive pair separated
        from the previous pair with a single comma, where <code>cc</code> indicates
        the channel number and <code>lll</code> indicates the line number for that
        channel (<code>0-255</code>). To leave a particular FCB channel undefined
        either specify <code>0</code> for the line number or simply don't specify
        that channel anywhere in your list.
        <p>
        The <code>name</code> format specifies the name of a predefined fcb image.
        Valid predefined fcb image names are: <code>legacy</code>, <code>fcb2std2</code>,
        <code>fcb2id1</code> or <code>hardware</code>. The default if not
        specified is <code>legacy</code>.

        <blockquote>
            <code><b><u>legacy</u></b>: &nbsp; &nbsp; fcb=01:01,02:07,03:13,04:19,05:25,06:31,07:37,08:43,09:63,10:49,11:55,12:61</code>
            <br>
            <code>fcb2std2: &nbsp; fcb=01:01,02:07,03:13,04:19,05:25,06:31,07:37,08:43,09:49,10:55,11:61,12:63</code>
            <br>
            <code>fcb2id1: &nbsp; &nbsp;fcb=01:01,02:08,03:15,04:22,05:29,06:36,07:43,08:50,09:57,10:64,11:71,12:78</code>
            <br>
            <code>hardware: &nbsp; fcb=01:01</code>
        </blockquote>

        Note that the <u>lines per page</u> value is not supported by the
        new or <code>name</code> formats of the <code>fcb</code> option.
        Instead, you must specify your desired lines per page value separately
        via the <code>lpp</code> option.
        <p>

    <dt><code>fcbcheck</code> &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; <i>(deprecated)</i>
    <dd><p>
        This option is only valid for 3203 or 3211 printer devices.
        It requests that an attempt to skip to a FCB channel for which
        no line number has been set should cause a Unit Check to occur.
        This is the default. This option is deprecated and will be removed
        in a future release.
        <p>

    <dt><code>index= &nbsp;<i>[-]nn</i> | <u>0</u></code>
    <dd><p>
        Specifies the column number of the form (-31 to +31) where each print
        line should begin. This option is only valid for 3211 printer devices.
        For 3203 printer devices the option is accepted but is otherwise ignored.
        <p>
        Positive values prepend each print line with a number of blanks equal to
        one less than the index value, thus "indenting" the print line to reach
        the desired form column. An index value of 1 means flush-left.
        A negative value causes the first <code>nn</code> columns of each print
        line to be chopped off. A value of -1 will thus cause the first character
        of each print line to be dropped, thereby causing the first column of
        the page to begin with the second character of each printed line.
        <p>
        The default is 0 meaning to print normally (i.e. indexing is disabled).
        <p>

    <dt><code>lpi= &nbsp;<u>6</u> | 8</code>
    <dd><p>
        Specifies the number of vertical lines per inch. The only valid values
        are either 6 or 8. The default is 6.
        <p>

    <dt><code>lpp= &nbsp;<i>nnn</i> | <u>66</u></code>
    <dd><p>
        Specifies the number of vertical lines per page (1-255). The default is 66.
        <p>

    <dt><code>noclear</code> &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; <i>(deprecated)</i>
    <dd><p>
        This option is deprecated and will be removed in a future
        release.  Please use the more aptly named <code>append</code>
        option instead.
        <p>

    <dt><code>nofcbcheck</code> &nbsp; &nbsp; &nbsp; &nbsp; <i>(deprecated)</i>
    <dd><p>
        This option is only valid for 3203 or 3211 printer devices.
        It requests that an attempt to skip to a FCB channel for which no
        line number has been set should suppress the Unit Check that would
        normally occur and to instead simply print the next line of output
        on the next line instead. It is the opposite of the <code>fcbcheck</code>
        option.
        <p>
        This option is deprecated and will be removed in a future release.
        The option will continue to be accepted for the time being if specified,
        but is otherwise completely ignored. Skips to non-existent FCB channels
        will always cause a Unit Check regardless of this option.
        <p>

    <dt><code>sockdev</code>
    <dd><p>
        Indicates the line printer 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: <code>port</code> or <code>host:port</code>.
        The device then accepts
        remote connections on the given TCP/IP port,
        and writes data to the socket instead of to a device
        file. This allows automatic remote spooling of line printer
        data. The sockdev option is mutually exclusive with the
        <code>crlf</code> and <code>append</code> options.
        <p>
    </dl>

    <p>

    If the printer filename begins with a vertical bar '&#124;' pipe character,
    then it is removed and the remainder of the filename is interpreted as
    a command line (the name of a program or batch file 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.

    <p>
    If the "print-to-pipe" command line contains arguments, then quotes
    must be placed around the entire filename, including the vertical bar,
    since any tokens following the filename are parsed as Hercules printer
    device options:
    <pre>
    000E 1403 "|/usr/bin/lpr -Phplj"               <em>(for Unix)</em>
    000E 1403 "|c:\utils\pr -s -PLPT1:" crlf       <em>(for Windows)</em></pre>
    <p>
    If the "print-to-pipe" command line itself contains quotes, then
    the command line must be enclosed in apostrophes instead of quotes,
    for example:
    <pre>
    000E 1403 '|"c:\Program Files\My Utils\pr" -s -PLPT1:' crlf</pre>
    <p>
    <a href="http://www.timpinkawa.net/hercules/prtspool.html">Tim Pinkawa</a>
    has an example which shows how the print-to-pipe feature can be used to
    create output in PDF format. For Windows users, SoftDevLabs provides a very
    nice PDF spooler for Hercules called
    "<a href="http://www.softdevlabs.com/hercprt">HercPrt</a>".
    <p><br>

<hr width="50%"><p>

<a name="3420"></a>
<a name="tapedev"></a>
<dt><em>Tape devices</em>
<dd><p>
    Five types of tape emulation are supported (see further below): &nbsp;
    <a href="#AWS">AWS</a>, &nbsp;
    <a href="#HET">HET</a>, &nbsp;
    <a href="#FAKETAPE">FakeTape</a>, &nbsp;
    <a href="#OMA">Optical Media Attach (OMA)</a>, &nbsp; and &nbsp;
    <a href="#SCSI">real SCSI</a> .
    <p>

    The only required parameter is the device filename. All other parameters
    are optional and must follow the filename. Use <code><big>*</big></code>
    (asterisk) for the filename to specify an empty (unmounted) tape drive.
    <p>

    If the specified device filename does not exist then either an unlabeled
    empty tape volume will be created for you automatically or a "file not
    found" error will occur depending on the setting of the <code>AUTOINIT</code>
    option. Refer to the <a href="#AUTOINIT"><code>AUTOINIT</code></a> option
    for more information.

    <p>
    If the file name starts with the <code><big>@</big></code> (at sign) character
    the file instead describes an Automatic Cartridge Feeder (ACF) file containing
    a list of tape emulation files to be automatically loaded in succession.

    The syntax of each line is identical to the information that can be
    specified in the configuration file after the device type.
    If the emulation file filename in the file list is the <code><big>*</big></code>
    (asterisk) character however, then the set of options which follow it apply
    to all of the remaining emulation files in the list.
    <p>

    Parameters are appended in succession. In all cases, if 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 <code><big>*</big></code> line, and another set for each
    individual line. Parameters are then appended in that order: options specified on
    the base device statement itself first, followed by those options specified on
    the <code><big>*</big></code> statement, and finally those specified on each individual
    file list statement last.
    <p>

    <i>A device filename identifying a <b>SCSI tape</b> device cannot be specified
    in an Automatic Cartridge Feeder (ACF) file list.</i>
    <p>

    Refer to the distributed source-code's
    <a href="https://github.com/sdl-hercules-390/hyperion/blob/master/readme/README.TAPE.md">README.TAPE</a>
    document for additional information regarding system and application programming
    for tape devices and instructions regarding use of the emulated <b>ACF</b>
    (Automatic Cartridge Feeder) and <a href="#AUTOMOUNT">AUTOMOUNT</a> features
    for virtual (non-SCSI) tape devices.
    <p>

    <dl> <!-- begin Emulated tape types of emulation -->

<a name="AWS"></a>
    <dt><b>AWSTAPE virtual tape files</b>
    <dd><p>
        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 <code>ickdsf.aws</code>)
    <p>

<a name="FAKETAPE"></a>
    <dt><b>FakeTape virtual tape files</b>
    <dd><p>
        These contain a complete tape in one file.  FakeTape files
        consist of variable length EBCDIC blocks.  Each block is
        preceded by a 12-ASCII-hex-character header.  Filemarks are represented by
        a 12-character header with no data.  The FakeTape format is
        used by the Flex-ES system from Fundamental Software Inc (FSI).
        The argument specifies the location of the FakeTape file
        (for example <code>ickdsf.fkt</code>). Note: "FLEX-ES" and
        "FakeTape" are trademarks of Fundamental Software, Inc.
    <p>

<a name="HET"></a>
    <dt><b>HET virtual tape files</b> &nbsp;&nbsp; (<b>H</b>ercules <b>E</b>mulated <b>T</b>ape)
    <dd><p>
        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 <code>023178.het</code>)
        <p>

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

        <dl> <!-- begin Additional HET arguments -->
        <dt><code>AWSTAPE</code>
        <dd><p>
            The <code>AWSTAPE</code> argument causes HET files to
            be written in AWSTAPE format.  This basically, disables
            the additional features provided by the HET format.
            <p>

        <dt><code>COMPRESS=<em><u><b>1</b></u></em>&#124;<em>0</em></code>
        <dt><code>IDRC=<em><u><b>1</b></u></em></code>&#124;<em>0</em></code>
        <dd><p>
            <code>COMPRESS</code> and <code>IDRC</code> control
            whether compression should be used when writing to HET
            files.  The value <code><em>n</em></code> &nbsp;can be <code>1</code>
            to turn on compression <i>(the default)</i> or <code>0</code> to turn
            it off.  <code>IDRC</code> is currently a synonym for
            <code>COMPRESS</code>, but may be used in the future to
            control other emulated tape drive features.
            <p>

        <dt><code>METHOD=<em><u><b>1</b></u></em>&#124;<em>n</em></code>
        <dd><p>
            The <code>METHOD</code> option allows you to specify
            which compression method to use.  You may specify
            <code>1</code> for ZLIB compression or <code>2</code>
            for BZIP2 compression.  The default is <code>1</code> <i>(zlib)</i>.
            <p>

        <dt><code>LEVEL=<em><u><b>4</b></u></em>&#124;<em>n</em></code>
        <dd><p>
            The <code>LEVEL</code> option controls the level of
            compression.  It ranges from <code>1</code> for fastest
            compression to <code>9</code> &nbsp;for best compression.
            The default is <code>4</code>.
            <p>

        <dt><code><u>CHUNKSIZE=<em><b>65535</b></em></u></code>
            &nbsp;&#124;&nbsp; <code>CHUNKSIZE=<em>nnnnn</em></code>
        <dd><p>
            The <code>CHUNKSIZE</code> 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
            e.g. 27998, those blocks would be broken down into
            <code><em>nnnnn</em></code> &nbsp;sized chunks.
            <p>
            The range is from <code>4096</code> to <code><u>65535</u></code>,
            with 65535 being the default. If 0 is specified, the default is used.
            Decreasing the value from its default may reduce compression performance.
            For compatibility with AWSTAPE files created by the P/390, specify
            the <code>AWSTAPE</code> option with <code>CHUNKSIZE=4096</code>.
            <p>

        </dl> <!-- end Additional HET arguments -->

    <p>

<a name="TAPE_ADD_PARMS"></a>
    <dt>The following additional parameters apply to
        <b><a href="#AWS">AWS</a></b>, <b><a href="#HET">HET</a></b>
        and <b><a href="#FAKETAPE">FakeTape</a></b> virtual tape files:
    <dd><p>

        <dl> <!-- begin Additional AWS/HET/FAKE parameters -->

        <dt><u><code>MAXSIZE=<b>0</b></code></u>
            &nbsp;&#124;&nbsp; <code>MAXSIZE</code>=<i>nnn</i>
            &nbsp;&#124;&nbsp; <code>MAXSIZE<b>K</b></code>=<i>nnn</i>
            &nbsp;&#124;&nbsp; <code>MAXSIZE<b>M</b></code>=<i>nnn</i>
            &nbsp;&#124;&nbsp; <code>MAXSIZE</code>=<i>nnn<b>S</b></i>
        <dd><p>
            Specifies the maximum size (in nnn bytes,
            <i><b>K</b></i>ilobytes or
            <i><b>M</b></i>egabytes)
            that the emulated file is allowed to grow to.
            <p>
            Or, <i>nnn<b>S</b></i> where <i><b>S</b></i> is either K (kilo),
            M (mega), G (giga), or T (tera) bytes.&nbsp;T may not be available on all platforms.
            <p>
            The default is 0 (zero), meaning unlimited. When 0 is specified,
            the <code>EOTMARGIN</code> parameter is ignored.
            <p>

        <dt><u><code>EOTMARGIN=<b>128K</b></code></u>
            &nbsp;&#124;&nbsp; <code>EOTMARGIN</code>=<i>nnn<b>S</b></i>
        <dd><p>
            Specifies the number of bytes remaining before reaching <code>MAXSIZE</code>
            at which point the tape device will signal the presence of the "End of Tape"
            marker (reflector), thus allowing the program to switch to the next tape.
            The value is either <i>nnn</i> (bytes), or <i>nnn<b>S</b></i> where <i><b>S</b></i>
            is either K, M, G, or T. The <code>EOTMARGIN</code> parameter ignored
            when <code>MAXSIZE=0</code> is specified.
            <p>

        <dt><code>READONLY</code>=<em>n</em>
        <dd><p>
            Specifies whether the tape is mounted read-only (without a write
            ring or with the cartridge protect switch set to "write
            protect").  A parameter of 1 means read-only; a parameter of 0
            means read-write.  If READONLY=1, RO or NORING is not specified,
            the default is READONLY=0.  Note that READONLY=0 does not override
            the host system file permission settings for the underlying AWS or
            HET file.  If the AWS or HET file is marked read-only, the tape
            will be mounted read-only despite specification of READONLY=0.
            <p>

        <dt><code>RO</code>
        <dt><code>NORING</code>
        <dd><p>
            Specifies that the tape is mounted read-only (without a write
            ring or with the cartridge protect switch set to "write
            protect").  RO and NORING are equivalent to READONLY=1.
            <p>

        <dt><code>RW</code>
        <dt><code>RING</code>
        <dd><p>
            Specifies that the tape should be mounted read-write, if possible.
            RW and RING are equivalent to READONLY=0.  This is the default if
            RO, NORING or READONLY=1 is not specified.  Note that RW and RING
            do not override the host system file permission settings for the
            underlying AWS or HET file.  If the AWS or HET file is marked
            read-only, the tape will be mounted read-only despite specification
            of RW or RING.
            <p>

        <dt><code>DEONIRQ</code>=<em>n</em>
        <dd><p>
            Specifies whether a device end is presented if intervention is
            required during tape motion. A parameter of 1 selects this
            option; a parameter of 0 turns it off.
            <p>

<a name="noautomount"></a>
        <dt><code>NOAUTOMOUNT</code>
        <dd><p>
            Indicates support for guest-initiated automatic tape volume
            mounting is to always be disabled for this tape device.
            <p>
            Automatic guest tape-mount support is automatically globally
            enabled for all virtual (non-SCSI) tape devices by default
            whenever an allowable automount directory is defined via the
            <a href="#AUTOMOUNT">AUTOMOUNT</a> configuration file statement
            or the <code>automount</code> panel command.
            The <code>NOAUTOMOUNT</code> option allows you to specifically
            disable such support for a given device.
            <p>
            The automount feature enables software running in guest operating
            systems to automatically mount, unmount and/or query for themselves
            the host "virtual tape volume" filename mounted on a tape drive,
            via the use of special CCW opcodes (0x4B Set Diagnose and 0xE4
            Sense Id) without any intervention on the part of the Hercules
            operator. An example of such a program for DOS/VSE called
            <code><a href="https://github.com/SDL-Hercules-390/hyperion/blob/master/util/TMOUNT.txt">TMOUNT</a></code>
            is provided in the <code>util</code>
            subdirectory of the distributed source code.
            <p>
            This is a sticky option. When specified, automount support for
            the device remains disabled until the option is specifically
            removed via a <code>devinit</code> command <em>without</em> the option
            specified. This means if <code>NOAUTOMOUNT</code> is enabled
            for a device while global automount functionality is currently
            disabled (because no <a href="#AUTOMOUNT">AUTOMOUNT</a> statement
            was specified at Hercules startup), then automount functionality
            remains disabled for the device even should global automount
            functionality be later manually enabled via an
            <code>automount</code> panel command.
            <p>
            When the 0x4B Set Diagnose CCW is used to auto-mount a virtual
            tape volume onto a given tape drive, an absolute (fully-qualified)
            pathname should normally always be specified, but need not be
            if a path relative to the currently defined "default allowable"
            automount directory is used instead.
            <p>
            The default allowable
            automount directory is always the first "allowable" directory
            that was defined, or else the current directory if no allowable
            directories were specifically defined. (There is always a default
            allowable directory whenever any allowable or unallowable automount
            directories are defined.)
            <p>
            Fully-resolved, absolute-full-path filenames are defined as being
            those which, for Windows, have a ':' (colon) in the second
            position or, for other host operating systems (e.g. Linux), have
            a '/' (slash) in the first position. Paths which start with a '.'
            (period) are considered relative paths and will always be appended
            to the currently defined default allowable automount directory,
            before being resolved into fully-qualified paths by the host system.
            (I.e. only fully-resolved absolute pathnames are used in the
            performance of the actual automatic tape volume mount.)
            <p>
            For example, if more than one allowable automount directory is
            defined and the volume wishing to be mounted happens to reside in
            the second one, then a fully-qualified absolute pathname should
            of course be specified (or else one that is relative to the
            default directory which happens to resolve to the desired file).
            <p>
            All attempts to automount host files in a "disallowed"
            directory or any of its subdirectories will be rejected.
            Similarly any attempt to automount a file which is not
            within any "allowable" directory or subdirectory will
            be rejected. An error message is always issued in such cases.
            A message is also issued whenever a successful mount or unmount
            is performed.
            <p>
            A sample guest automount program called
            <code><a href="https://github.com/SDL-Hercules-390/hyperion/blob/master/util/TMOUNT.txt">TMOUNT</a></code>
            for the DOS/VSE operating system is provided in the
            <code>util</code> subdirectory of the distributed source code.

        </dl> <!-- end Additional AWS/HET/FAKE parameters -->

    <p>

<a name="OMA"></a>
    <dt><b>Optical Media Attach (OMA) virtual tape files</b>
    <dd><p>
        These are read-only files which usually (but do not necessarily
        have to) reside on CDROM. OMA virtual tapes consist of one 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 <code>/cdrom/tapes/uaa196.tdf</code>)
        <p>
        The format of a Tape Descriptor File (TDF) looks like this:
        <p>
        <pre>
        @tdf
        /home/ivan/hercules/systems/DEB001/kernel.debian    FIXED RECSIZE 80
        /home/ivan/hercules/systems/DEB001/parmfile.debian  TEXT
        /home/ivan/hercules/systems/DEB001/initrd.debian    FIXED RECSIZE 80</pre>or:<pre>
        @TDF
        "C:\Users\Fish\HercGUI\_Z\zLinux Debian-9.11\kernel.debian"    FIXED RECSIZE 80
        "C:\Users\Fish\HercGUI\_Z\zLinux Debian-9.11\parmfile.debian"  TEXT
        "C:\Users\Fish\HercGUI\_Z\zLinux Debian-9.11\initrd.debian"    FIXED RECSIZE 80
        TM
        TM
        EOT</pre>or:<pre>
        @tdf
        kernel.debian    FIXED RECSIZE 80
        parmfile.debian  TEXT
        initrd.debian    FIXED RECSIZE 80</pre>

        The filename on each record can be either absolute or relative and must be
        enclosed within double quotes it it contains any spaces. If relative, the
        name is appended to the path of the primary OMA (TDF) to create the full
        path filename of the file being referenced.
        <p>
        Each file record must be followed by a file <i>format</i> (and possibly
        some additional options) indicating how the file should be interpretted.
        Each file listed in the TDF file must be in one of four formats:
        <p>

        <dl>
        <dt><code>UNDEFINED RECSIZE <em>nnnnn</em></code>
        <dd><p>
            <b><i>UNDEFINED</i></b> files are treated identically
            to FIXED files.
            <p>

        <dt><code>FIXED RECSIZE <em>nnnnn</em></code>
        <dd><p>
            <b><i>FIXED</i></b> files consist of fixed length
            EBCDIC blocks of the specified length
            (<code><em>nnnnn</em></code>)
            <p>

        <dt><code>TEXT</code>
        <dd><p>
            <b><i>TEXT</i></b> 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.
            <p>

        <dt><code>HEADERS</code>
        <dd><p>
            <b><i>HEADERS</i></b> files consist of variable
            length EBCDIC blocks.  Each block is preceded by a
            16-byte header.
            <p>

        </dl>
        <p>

        If you have any IBM manuals in Bookmanager format on CDROM,
        you can see some examples of TDF files in the <code>\TAPES</code>
        directory on the CDROM. The offical OMA/2 format is described in
        manuals <i>SC52-1200-00 "Optical Media Attach/2 User's Guide"</i>
        and <i>SC52-1201-00 "Optical Media Attach/2 Technical Reference"</i>,
        but both are impossible to find.

    <p>

<a name="SCSI"></a>
    <dt><b>Real SCSI attached tape drives</b>
    <dd><p>
        These are real tape drives attached to the host machine via a SCSI
        interface. Hercules emulation always makes the drive appear as a
        channel attached device such as 3420 or 3480, although the underlying
        physical drive may be any type of SCSI attached tape drive, including
        4mm or 8mm DAT, DLT, SCSI attached 3480/3490/3590 cartridge drives,
        and SCSI attached 3420 open reel tape drives.
        <p>
        Host-attached SCSI tapes are read and written using variable length
        EBCDIC blocks and filemarks exactly like a mainframe tape volume, and
        as a result can be freely used and/or exchanged on either one (i.e.
        SCSI tapes created on a real mainframe can subsequently be read by
        Hercules just fine, and a SCSI tape created by Hercules can be subsequently
        read on a mainframe just fine, thus providing a convenient means of
        exchanging data between the two).
        <p>
        If you plan on using SCSI tapes with Hercules you might also be interested
        in the <a href="#SCSIMOUNT">SCSIMOUNT</a> configuration option.
        <p>
        The only <i>required</i> device statement parameter for SCSI attached tape
        drives is the name of the device as it is known
        by the host operating system,
        usually &nbsp;"<code><b>/dev/nst0</b></code>"&nbsp; <i>(for Linux or
        Windows)</i> or &nbsp;"<code><b>\\.\Tape0</b></code>" &nbsp; <i>(for
        Windows only)</i>, where '0' means tape drive number
        0 (your first or only host-attached SCSI tape drive), '1' means your
        second host-attached SCSI tape drive, etc.
        <p>
        Depending on what actual model of SCSI tape drive you
        actually have and how it behaves, you may need to specify one or more
        additional optional parameters for Hercules to provide proper emulation
        of the desired device type.
        For example: a <b>Quantum 'DLT' (Digital Linear Tape) SCSI</b> tape drive
        does not return nor use a block-id format compatible with 3480/3490 drives
        (it instead uses a full 32-bit block-id just like the model 3590 does).
        It also does not support the Erase Gap command at all.
        <p>
        Thus, in order to use, for example, a Quantum DLT drive with Hercules,
        you <i>MUST</i> specify some special additional options to prevent the
        Erase Gap command from being issued to the drive as well as to inform
        Hercules that the drive uses 32-bit block-ids.
        <p>
        <b>Please note</b> that the below options define how the actual SCSI hardware
        device behaves, which is completely different from the way the <i>emulated</i>
        device will appear to behave to your guest. That is to say, if you define
        your tape drive to Hercules as a 3480 device, then Hercules will perform
        3480 device type emulation such that the device appears to your guest o/s
        as if it were a 3480 device. If the <i>actual</i> SCSI device behaves as
        a 3590 device however (perhaps using/returning 32-bit block-ids instead
        of the expected 22-bit format block-ids that 3480's use), then you <i>MUST</i>
        specify the <code>--blkid-32</code> special option on your Hercules device
        statement so that Hercules's emulation logic can know that it needs to
        translate 22-bit block-ids to 32-bit ones before sending them to the
        actual SCSI hardware (and vice versa: to translate 32-bit block-ids from
        the actual SCSI drive into 22-bit format block-ids that your guest expects
        from a 3480 device).
        <p>

<a name="Quantum"></a>
                <center><h4>Special options for SCSI tapes</h4></center>
        <p>
        As explained just above, certain model SCSI tape drives such as the Quantum
        DLT series may require special handling in order to provide the desired proper
        device type emulation. These special options are:
        <p>
        <dl>
        <dt><code>--blkid-22</code>
        <dd><p>
            The complete opposite of the below <code>--blkid-32</code> option.
            Use this option if your real SCSI tape drive behaves as a 3480/3490
            and expects 22-bit block-ids, but you wish to define the drive to
            Hercules as a 3590 tape drive (which uses 32-bit block-ids).
            <p>
        <dt><code>--blkid-32</code>
        <dd><p>
            This option indicates that your SCSI attached tape drive only
            supports 32-bit block-ids (as used by 3590 drives) and not the 22-bit
            format used by 3480/3490 drives. You should only specify this option
            if you intend to define the drive as a model 3480 or 3490 device
            to Hercules, and then only if your actual real SCSI drive uses 32-bit
            block-ids.
            <p>
            If you define your Hercules tape drive as a model 3590 device however,
            then this option is not needed since model 3590 drives are already
            presumed to use 32-bit block-ids.
            <p>
            Specifying this option on a 3480/3490 device statement will cause
            Hercules device emulation logic to automatically translate the actual
            SCSI tape drive's 32-bit block-id into 22-bit format before returning
            it back to the guest operating system (since that is the format the
            guest operating system expects it to be in for a model 3480/3490 drive),
            and to translate the guest's 22-bit format block-id into 32-bit format
            before sending it to the actual SCSI hardware (since that is the format
            that the actual hardware requires it to be in).
            <p>
        <dt><code>--no-erg</code>
        <dd><p>
            This option is intended to prevent issuance of the Erase Gap
            command to those SCSI tape drives which do not support it (such
            as the Quantum DLT series). It causes Hercules's device emulation
            logic to ignore any Erase Gap commands issued to the drive and
            to return immediate 'success' instead.
            <p>
            This option should
            only be used (specified) for drives such as the Quantum, which
            support switching from read mode to write mode in the middle of
            a data stream without the need of an intervening Erase Gap command.
            Specifying it for any other model SCSI drive may cause incorrect
            functioning as a result of the Erase Gap command not being issued
            to the actual SCSI hardware.
            <p>
            Check the manufacturer information for your particular model of
            SCSI attached tape drive (and/or use SoftDevLabs's
            "<a href="http://www.softdevlabs.com/ftape">ftape</a>"
            Windows utility)
            to determine whether or not this option is needed for your
            particular drive.
            <p>
        <dt><code>--online</code>
        <dd><p>
            Use this option if your host's magtape device driver sets the
            GMT_ONLINE status flag to report when a tape is mounted instead
            of the more common behavior of clearing the GMT_DR_OPEN flag.
            <p>
            Debian 8.3 Linux systems running on HP (Hewlett Packard) hardware
            using StorageTek 9840 fiber channel drives or DEC TSZ07 9-track
            drives (via a fc/SCSI bridge) for example, are known to <i>not</i>
            use the GMT_DR_OPEN flag <i>at all</i>. Rather, they set the GMT_ONLINE
            status flag to indicate when a tape is mounted, thus requiring the
            <code>--online</code> option to work properly with Hercules.
        </dl>

    <p>

    </dl> <!-- end Emulated tape types of emulation -->

<hr width="50%"><p>

<a name="COMM"></a>
<dt><em>Communication and Channel-to-Channel devices</em>
<dd><p>
    The first argument defines the emulation type, and the remaining
    arguments depend on the chosen emulation type.
    <p>

    The following are the emulation types that are currently supported:
    <p>

    <dl> <!-- begin emulation types -->

<a name="QETH"></a>
    <dt><b>QETH</b> &nbsp; &nbsp; (OSA/QDIO Ethernet Adapter)
    <dd><p>

        Emulates an OSA Express card running in QDIO mode.
        Both layer-2 and layer-3 are currently supported.
        The mode of operation is selected by the emulated workload
        and cannot be configured from Hercules.

        </p>

        <p>

        The QETH device is a "grouped" device that requires 3 (three) device
        addresses (device numbers) to be defined per QETH group, with the
        first device of the group being an even numbered device:

            <blockquote>
            <code>0600<b>.3</b> &nbsp; QETH &nbsp;<i>[arguments...]</i></code>
            </blockquote>

        You may also optionally use <code>OSA</code> or <code>OSD</code>
        as the device/emulation type instead of <code>QETH</code> if desired:

            <blockquote>
            <code>0600.3 &nbsp; OSA &nbsp;&nbsp;<i>[arguments...]</i></code><br>
            <code>0600.3 &nbsp; OSD &nbsp;&nbsp;<i>[arguments...]</i></code>
            </blockquote>

        </p>

        <p>

        <p class="box">
        <i>
        <b>Note:</b> Hercules's networking support <u>MAY</u> require <u>privileged access</u>
        to your host's networking devices depending on whether you use pre-configured networking
        interfaces or not, which means Hercules itself <u>MAY</u> need to be started with
        Administrative (root) privileges. (Refer to the discussion in the
        <a href=#netpriv>NETDEV</a> statement.)
        </br></br>
        The easiest way to do this on Linux et al. is to enable setuid for hercifc using the
        <tt>--enable-setuid-hercifc</tt> configure option. If that's not possible (or
        you're not running Hercules under Linux et al), then Hercules <u>must</u> be started
        with Administrative (root) privileges or your Hercules networking devices will not work.
        </i>

        <br><br>

        <i>
        <b>Please also note</b> that the QETH (OSA) device is still considered to be an experimental
        driver still under development. Not all of the features or functionality
        that real OSA devices have are currently supported. For example, the
        current implementation only supports three devices: the read device,
        the write device and the datapath device. Real OSA devices support
        multiple datapath devices. Support for this feature is planned, but is
        not yet implemented. Regardless, QETH (OSA) device support appears to be stable
        and has been working fine without any problems for several years now.
        </i>

        </p>

        <dl> <!-- begin QETH parms -->

        <dt>Arguments:
        <dd><p>

            <dl>

                <dt><code>ifname &nbsp;<em>interface</em></code>
                <dd><p>
                    <b><i>Only available on *nix</i></b><br>
                    Specifies the interface name for the device to be created
                    (e.g. <code>tun</code>, <code>tun0</code>, etc).
                    <p>

            </dl>

            <dl> <!-- begin Optional for both *nix and Windows -->

                <dt><code>ipaddr &nbsp;<em>address</em></code>
                <dt><code>ipaddr &nbsp;<em>address/prefix</em></code>
                <dd><p>
                    <b><i>Required on Windows</i></b><br>
                    Specifies the IPv4 address to be assigned to your virtual
                    OSA Express card. This IP Address should match the IP
                    address in your guest's TCPIP PROFILE, although this is
                    not a requirement; during guest initialization your guest
                    should automatically assign the proper IP address to your
                    OSA device.
                    <p>
                    The address can be optionally followed by a prefix size
                    expressed in CIDR notation, e.g. <code>192.168.1.1/24</code>.
                    For IPv4 the prefix size can have a value from 0 to 32.
                    If not specified a value of 32 is assumed.
                    The prefix size is used to produce an equivalent subnet mask.
                    For example, a value of 24 produces a subnet mask of 255.255.255.0.
                    Otherwise the subnet mask must be specify via the
                    <code>netmask</code> parameter.

                    <p>

                <dt><code>netmask &nbsp;<em>mask</em></code>
                <dd><p>
                    Specifies the subnet mask to be used with your OSA card.
                    On Windows, this value should be the same subnet mask that
                    your Windows system is using (i.e. that the 'iface' adapter
                    is using).
                    <p>
                    The <code>netmask</code> option may only be specified when
                    the subnet mask is not already defined via the optional
                    prefix size parameter of the <code>ipaddr</code> option.
                    <p>

                <dt><code>iface &nbsp;<em>device</em></code>
                <dd><p>
                    Specifies, on Linux, the name of the host tunnel device to use. On
                    Windows, this required option identifies your Windows system's actual
                    network adapter.
                    On Linux, the value should be specified by name (e.g. /dev/net/tun). On
                    Windows, the value should be specified by either IP or MAC address.
                    <p>
                    The default value for this option is the same value specified in your
                    <a href="#netdev">NETDEV</a> configuration file statement (or the default
                    value if not specified).
                    <p>

                <dt><code>ipaddr6 &nbsp;<em>address</em></code>
                <dt><code>ipaddr6 &nbsp;<em>address/prefix</em></code>
                <dd><p>
                    Specifies the IPv6 address to be assigned to your OSA card.
                    <p>
                    The address can be optionally followed by the prefix size
                    expressed in CIDR notation, e.g.
                    <code>2001:db8:3003:1::543:210f/48</code>.
                    For IPv6 the prefix size can have a value from 0 to 128. If
                    not specified a value of 128 is assumed. The prefix size
                    is used to produce an equivalent subnet mask.
                    <p>

                <dt><code>hwaddr &nbsp;<em>MAC</em></code>
                <dd><p>
                    Specifies the MAC address to be assigned to your OSA card.
                    <p>
                    If not specified then one will be internally generated
                    in the range 02:00:5E:80:00:00 - 02:00:5E:FF:FF:FF using
                    the low order 23 bits of the IPv4 address. For example,
                    if the ipv4 address is 10.1.2.3 the generated MAC address
                    will be 02:00:5E:81:02:03.
                    <p>
                    <i>
                    <b>Note:</b> The MAC address you specify for this option MUST have
                    the 02 locally assigned MAC bit on in the first byte, must NOT have
                    the 01 broadcast bit on in the first byte, and MUST be unique as seen
                    by all other devices on your network segment.
                    It should never, for example, be the same as the host adapter MAC
                    address specified on the <code><em>iface</em></code> parameter.
                    </i>
                    <p>

                <dt><code>mtu &nbsp;<em>bytes</em></code>
                <dd><p>
                    Specifies the Maximum Transmission Unit to be used.
                    The maximum transmission unit (MTU) is the largest
                    packet size, measured in bytes, that can be transmitted
                    over a network.
                    <p>
                    On Windows, if the value is not specified or is larger than
                    what <a href="http://www.softdevlabs.com/ctci-win">CTCI-WIN's</a>
                    WinPCap driver can support for the specified
                    <code>iface</code> host adapter, a warning is issued and the
                    specified value is ignored and the maximum supported value
                    is used instead.
                    <p>

                <dt><code>chpid &nbsp;<em>id</em></code>
                <dd><p>
                    Specifies the channel path identifier to be used with the device.
                    <p>
                    This is mostly a cosmetic value, but some guest operating systems
                    such as z/OS might require it to operate correctly.
                    <p>

                <dt><code>debug</code>
                <dd><p>
                    Enables debug logging for the device.
                    <p>
                    When logging is enabled the Hercules driver logs
                    extra progress and status messages used to help
                    debug an incorrectly functioning driver. The
                    Hercules <code>qeth</code> panel command can be used
                    to limit the type of debug information that is logged.
                    Enter the command <code>help qeth</code> for more
                    information.
                    <p>

            </dl> <!-- end Optional for both *nix and Windows -->

        </dl> <!-- end QETH parms -->

<p><br>

<a name="LCS"></a>
    <dt><b>LCS</b> &nbsp; &nbsp; (LAN Channel Station Emulation)
    <dd><p>
        An emulated Lan Channel Station Adapter.
        This emulation mode appears to the operating system running in
        the Hercules machine as either an IBM 8232 LCS device, the LCS3172
        driver of a P/390, a 3172 running ICP (Interconnect Communications
        Program), or as a simple IBM 2216 router.

        <p>

        Beginning with SDL Hyperion version 4.4, an LCS device is now also capable of
        providing <a href="#SNA">SNA</a> support as well. Refer to the
        <a href="https://github.com/sdl-hercules-390/hyperion/blob/master/readme/README.SNA.md">README.SNA</a>
        document for details.

        <p>

        Except when defined as an <a href="#SNA">SNA</a> device, the LCS device is a "grouped" device
        that requires 2 (two) device addresses (device numbers) to be defined per
        LCS group, with the first device of the group being an even numbered device:

            <blockquote>
            <code>0E20<b>.2</b> &nbsp; LCS &nbsp;<i>[arguments]</i></code>
            </blockquote>

        <p>

        <p class="box">
        <i>
        <b>Note:</b> Refer to the discussion in the <a href=#netpriv>NETDEV</a> statement
        for important information regarding elevated privileges that <u>may</u> be required
        for networking devices.
        </i>
        </p>

        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.

        <p>

        There are no required parameters for the LCS emulation,
        however there are several options that can be specified on the
        device statement. Also note that on the MAC OS X platform, the
        long option format (--xxx) is not supported. On MAC, only the
        short option format (-x) should be used.

        <p>

        The format of the configuration statement for LCS devices is as follows:

        <p>

        <dl> <!-- begin LCS parms -->
        <dt><code>-n <em>devname</em></code> &nbsp;&nbsp; or &nbsp; <code>--dev <em>devname</em></code>
        <dd><p>
            where <em>devname</em> is:
            <p>

            <dl> <!-- begin 'devname' -->

                <dt>(Linux/Unix)
                <dd><p>
                    the name of the Tun/Tap special character device,
                    normally /dev/net/tun.
                    <p>

                <dt>(Windows)
                <dd><p>
                    either the IP or MAC address of the host system's network card.
                    <p>

             </dl> <!-- end 'devname' -->

            The default for this option is the value specified
            by the <a href="#netdev">NETDEV</a> configuration file statement.
            <p>

        <dt><code>-o <em>filename</em></code> &nbsp;&nbsp; or &nbsp; <code>--oat <em>filename</em></code>
        <dd><p>
            where <em>filename</em> specifies the filename of the
            OSA Address Table (OAT). If this option is specified, the optional
            <code>--mac</code> and <em>guestip</em> entries are ignored in preference to
            statements in the OAT. (See further below for the <a href=#OAT>syntax
            of the OAT</a>)
            <p>
            If no OAT is specified, the emulation module
            will create the following:
            <p>
            <ul>
                <li>An ethernet adapter (port 0) for TCP/IP traffic only.
                <li>Two device addresses will be defined (devnum and devnum + 1).
            </ul>
            <p>

        <dt><code>-m <em>MAC Address</em></code> &nbsp;&nbsp; or &nbsp; <code>--mac <em>MAC address</em></code>
        <dd><p>
            where <code><em>'MAC address'</em></code> is the optional hardware address
            for your guest's virtual adapter/interface in the format: hh:hh:hh:hh:hh:hh.
            The default value is '02:00:5E:nn:nn:nn' where the <i>:nn:nn:nn</i> portion
            is constructed from the last 3 octets of the specified
            <code><i>guestip</i></code>.
            <p>
            <i>
            <b>Note:</b> The MAC address you specify for this option MUST have the 02 locally
            assigned MAC bit on in the first byte, must NOT have the 01 broadcast bit
            on in the first byte, and MUST be unique as seen by all other devices on
            your network segment. It should never, for example, be the same as the host
            adapter MAC address specified on the <code><em>-n</em></code> parameter.
            </i>
            <p>
            Note: If you use the <code>--oat</code> option, do not specify an address
            here. Instead, specify your desired guest adapter MAC address in your OAT
            file via the <code>HWADD</code> statement.
            <p>

        <dt><code><em>guestip</em></code>
        <dd><p>
            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 <code>--oat</code> option,
            do not specify an address here.
            <p>

        <a name="OAT"></a>
        <dt><b>OAT syntax</b>
        <dd><p>

            The syntax for the OSA Address Table (OAT) is as follows:
            <p>
<a name="SNA"></a>
<table border=1 cellpadding=20><tr><td>
<pre><code>*****************************************************
* Dev    Mode   Port    Entry specific information  *
*****************************************************

  0400    IP     00     PRI  172.21.3.32
  0402    IP     00     SEC  172.21.3.33
  0404    IP     00     NO   172.21.3.38
  0406    IP     01     NO   172.21.2.16
  040E    SNA    00

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

ROUTE  00  172.21.3.32  255.255.255.224
</code></pre>
</td></tr></table>
            <p>

            <dl> <!-- begin LCS DEV/MODE parms -->
            <dt>where:
            <dd><p>
                <dl> <!-- (begin INDENT) -->
                    <dt><code><em>Dev</em></code>
                    <dd>is the base device address
                        <p>

                    <dt><code><em>Mode</em></code>
                    <dd>is the operation mode: IP or SNA.
                        <p>
                        <i><b>Note:</b> &nbsp;the SNA operation mode is currently
                        not implemented via the OAT file. Rather, a separate LCS
                        device with the <code>-e SNA</code> device option must be
                        specified instead. Refer to the
                        <a href="https://github.com/sdl-hercules-390/hyperion/blob/master/readme/README.SNA.md">README.SNA</a>
                        document for details.</i>
                        <p>

                    <dt><code><em>Port</em></code>
                    <dd>is the virtual (relative) adapter number (i.e. port number).
                        <p>
                </dl> <!-- (end INDENT) -->
            </dl> <!-- end LCS DEV/MODE parms -->
            <p>

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

            <p>

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

            <p>

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

            <p>

            <blockquote>
                <dl> <!-- begin IP Mode parms -->

                    <dt><code>PRI &#124; SEC &#124; NO</code>
                    <dd><p>
                        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.
                        <p>

                    <dt><code><em>nnn.nnn.nnn.nnn</code></em>
                    <dd><p>
                        Specifies the home IP address

                </dl> <!-- end IP Mode parms -->
            </blockquote>

            <p>

            When the operation mode is <code>IP</code>&nbsp; specify only the read
            (even) device number for <code><em>Dev</em></code>. The write (odd)
            address will be created automatically.

            <p>

            Additionally, a HWADD and/or ROUTE statement
            may also be included in the OAT:

            <p>

            <blockquote>
                <dl> <!-- begin HWADD and ROUTE -->

                    <dt><code>HWADD &nbsp;pp <i>&nbsp;hh:hh:hh:hh:hh:hh</i></code>
                    <dd><p>
                        Use the HWADD to specify a hardware (MAC) address for a
                        virtual adapter (port). The first parameter after HWADD
                        specifies the relative adapter (port) to which the address
                        is applied.

                        <p>

                        <i>
                        <b>Note:</b> The MAC address you specify for this option MUST have
                        the 02 locally assigned MAC bit on in the first byte, must
                        NOT have the 01 broadcast bit on in the first byte, and MUST
                        be unique as seen by all other devices on your network segment.
                        It should never, for example, be the same as the host adapter
                        MAC address specified on the <code><em>-n</em></code> parameter,
                        nor the same as the HWADD defined for any other port.
                        </i>

                        <p>

                    <dt><code>ROUTE &nbsp;pp <i>&nbsp;nnn.nnn.nnn.nnn &nbsp;...</i></code>
                    <dd><p>
                        The ROUTE statement is included for convenience. This requests
                        Hercules's network configuration logic (hercifc utility on
                        Linux or CTCI-WIN on Windows) to automatically 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 since this is done automatically by the
                        Hercules device driver's emulation module.

                        <p>

                </dl> <!-- end HWADD and ROUTE -->
            </blockquote>

        </dl> <!-- end LCS parms -->

<p><br>

<a name="CTCI"></a>
    <dt><b>CTCI</b> &nbsp; &nbsp; (Channel to Channel link to TCP/IP stack)
    <dd><p>
        A point-to-point IP connection with the TCP/IP stack of the
        driving system on which Hercules is running.  See the
        <a href="herctcp.html">Hercules TCP/IP</a> page for unix details,
        in particular the use of preconfigured interfaces.
        <p>

        The CTCI device is a "grouped" device that requires 2 (two) device
        addresses (device numbers) to be defined per CTCI group, with the
        first device of the group being an even numbered device:

            <blockquote>
            <code>0E20<b>.2</b> &nbsp; CTCI &nbsp;<i>[arguments]</i></code>
            </blockquote>

        <p>

        <p class="box">
        <i>
        <b>Note:</b> Refer to the discussion in the <a href=#netpriv>NETDEV</a> statement
        for important information regarding elevated privileges that <u>may</u> be required
        for networking devices.
        </i>
        </p>

        <p>
        The Windows implementation is different from the unix one. See
        SoftDevLab's <a href="http://www.softdevlabs.com/ctci-win">CTCI-WIN</a>
        page for further details and information.
        <p>
        For unix systems, such as Linux, BSD, and OSX, you may use
        preconfigured interfaces or you may
        request Hercules to configure the interface for you.
        In the first case you must know and supply the name of the interface to use;
        in the second case the kernel supplies an interface name.
        <p>

        <dl> <!-- begin CTCI parms -->
        <dt>Required for Linux when using a preconfigured interface:

        <dd><p>
            <dl>
                <dt><code><em>ifname</em></code>
                <dd><p>
                    Specifies the interface name of an
                    interface that is already configured.
                    The flag <code>--if</code> may optionally be specified
                    before the name.
                    <p>
                    Specify no IP addresses or other arguments as the
                    information is already configured into the interface.
                    <p>
            </dl>

        <dt>Required for Linux when not using a preconfigured interface,
        and for Windows:
        <dd><p>

            <dl> <!-- begin Required for both Linux and Windows -->

                <dt><code><em>guestip</em></code>
                <dd><p>
                    Specifies the IP address of the guest operating system
                    running under Hercules.
                    <p>

                <dt><code><em>hostip</em></code>
                <dd><p>
                    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.
                    <p>

            </dl> <!-- end Required for both Linux and Windows -->

            <p>

        <dt>Optional for Windows:
        <dd><p>
            If these arguments are specified, they must precede the required
            arguments.
            <p>

            <dl> <!-- begin Optional for Windows -->

                <dt><code>-m <em>MAC address</em></code> &nbsp;&nbsp; or &nbsp; <code>--mac <em>MAC address</em></code>
                <dd><p>
                    where <code><em>'MAC address'</em></code> is the optional hardware address
                    for your guest's virtual adapter/interface in the format: hh:hh:hh:hh:hh:hh.
                    The default value is '02:00:5E:nn:nn:nn' where the <i>:nn:nn:nn</i> portion
                    is constructed from the last 3 octets of the specified
                    <code><i>guestip</i></code>.
                    <p>
                    <i>
                    <b>Note:</b> The MAC address you specify for this option MUST have the 02 locally
                    assigned MAC bit on in the first byte, must NOT have the 01 broadcast bit
                    on in the first byte, and MUST be unique as seen by all other devices on
                    your network segment. It should never, for example, be the same as the host
                    adapter MAC address specified on the <code><em>-n</em></code> parameter.
                    </i>
                    <p>

                <dt><code>-k &nbsp;<em>kernel-capture-buffer-size</em></code>
                    <dd>
                <dt><code>-i &nbsp;<em>tuntap32-i/o-buffer-size</em></code>
                <dd><p>
                    See SoftDevLabs's
                    <a href="http://www.softdevlabs.com/ctci-win">CTCI-WIN</a>
                    page for further details and information.
                    <p>

            </dl> <!-- end Optional for Windows -->

            <p>

        <dt>Optional for both Linux and Windows:
        <dd><p>
            If these arguments are specified, they must precede the required
            arguments:
            <p>

            <dl> <!-- begin Optional for both Linux and Windows -->

                <dt><code>-n <em>name</em></code> &nbsp;&nbsp; or &nbsp; <code>--dev <em>name</em></code>
                <dd><p>
                    Specifies the name of the tunnel device to use.
                    The default is the value specified by the
                    <a href="#netdev">NETDEV</a> configuration file statement.
                    <p>

                <dt><code>-s <em>netmask</em></code>
                <dd><p>
                    where <em>netmask</em> is the netmask to use for the
                    automatically added point-to-point route in standard
                    dotted internet noitation (e.g. 255.255.255.0)
                    <p>

                <dt><code>-x <em>name</em></code> &nbsp;&nbsp; or &nbsp; <code>--if <em>name</em></code>
                <dd><p>
                    Specifies the name of the network interface to use.
                    <p>
                    There is no default for this argument as the kernel
                    assigns an interface name if none is provided.
                    <p>

                <dt><code>-d</code> &nbsp;&nbsp; or &nbsp; <code>--debug</code>
                <dd><p>
                    Specifies that debugging output is to be produced on the
                    Hercules control panel. This should normally be left
                    unspecified.
                    <p>

            </dl> <!-- end Optional for both Linux and Windows -->

        </dl> <!-- end CTCI parms -->

<p><br>

<a name="CTCE"></a>
    <dt><b>CTCE</b> &nbsp; &nbsp; (Enhanced Channel-to-Channel Emulation via TCP connection <i>(true 3088 CTCA)</i>)
    <dd><p>
        The CTCE device type emulates a true 3088 Channel to Channel
        Adapter.  CTCE devices are emulated via TCP/IP connections between
        two or more Hercules instances.
        <p>

        <p class="box">
        <i>
        <b>Note:</b> Refer to the discussion in the <a href=#netpriv>NETDEV</a> statement
        for important information regarding elevated privileges that <u>may</u> be required
        for networking devices.
        </i>
        </p>

        <p>
        A Hercules CTCE device requires two even-odd pairs of devices, one for
        reading and the other for writing.  In the previous CTCE version these had
        to be an even-odd pair of port numbers, whereby only the even port numbers
        had to be specified in the CTCE configuration.  This restriction has now
        been removed.  Any port number > 1024 and < 65534 is allowed.  The CTCE
        configuration specifies the listening port number at the receiving end,
        the sender side port number is a free randomly chosen one.
        <p>
        The socket connection pairs cross-connect,
        the arrows showing the send->receive direction :
        <pre>
        x-lport-random  -->  y-rport-config
        x-lport-config  <--  y-rport-random</pre>
        <p>
        CTCE connected Hercules instances can be hosted on either Unix or Windows
        or MacOS platforms.  Neither side needs to be the same as the other.
        Each side can be different from the other if needed. One side
        can be Windows and the other side can be Linux if so desired.
        <p>
        The configuration statement for CTCE devices is in one of these 2 possible
        formats (noting that items between [] brackets are optional):
        <p>
        <dl> <!-- begin CTCE parms -->
        <dt><code><em>ldevnum</em> &nbsp;&nbsp;&nbsp; CTCE [<em>lport</em>] [<em>rdevnum</em>=]<em>raddress</em> &nbsp; <em>rport</em>  [[<em>mtu</em>]<em>sml</em>] [ATTNDELAY <em>delay</em>] [FICON]</code>
        <dt><code><em>ldevnum</em>[.n]                CTCE [<em>lport</em>] [<em>rdevnum</em>]=<em>raddress</em>       [<em>rport</em>] [[<em>mtu</em>]<em>sml</em>] [ATTNDELAY <em>delay</em>] [FICON]</code>
        </dl> <!-- end CTCE parms -->

        <p>
        <dl> <!-- begin required CTCE parameters -->
        <dt>There is only one or two <i>required</i> positional arguments in addition to the <em>ldevnum</em>:
        <dd><p>
            <dl>
                <dt><code><em>ldevnum</em></code>
                <dd>The device number (CCUU) on the <i>local</i> system.
                    Please note that this can optionally be followed by <em>.n</em> in
                    which case multiple CTCE devices can be configured with one config
                    statement.

                <p>

                <dt><code><em>raddress</em></code>
                <dd>The IP address of the remote system.

                <p>

                <dt><code><em>rport</em></code>
                <dd>The listening TCP/IP port number on the <i>remote</i> system.
                    Please note that this parameter is only required when the
                    <em>rdevnum</em> parameter and the following equal sign are
                    not specified, or when the <em>mtu</em> parameter needs to be
                    specified.  When not required, the default is 3088.
            </dl>
        </dl> <!-- end required CTCE parameters -->

        <p>

        <dl> <!-- begin optional CTCE parameters -->
        <dt>The remaining arguments are optional as per the shown [] brackets for the format chosen:
        <dd><p>
            <dl>
                <dt><code><em>lport</em></code>
                <dd>The listening TCP/IP port number on the <i>local</i> system.
                    The default value is 3088.

                <p>

                <dt><code><em>rdevnum</em></code>
                <dd>The device number (CCUU) on the <i>remote</i> system.
                    The default is equal to the <em>ldevnum</em> on the  <i>local</i> system.
                    Please note that in case only one or two hexadecimal digits are given (i.e. a
                    value up to 255 and thus not a complete device number CCUU), the effective
                    <em>rdevnum</em> will be computed by exclusive-or of this value with the
                    <em>ldevnum</em> specified.  In case <em>.n</em> is given and > 1, this
                    will apply to all <em>ldevnum</em> - <em>rdevnum</em> pairs.  Please see an
                    example of this down below.

                <p>

                <dt><code><em>mtu</em></code>
                <dd>Maximum Transmission Unit buffer size.
                    The default value is 62552 bytes.
                    Please note that when this <em>mtu</em> parameter needs to be specified, also
                    the <em>rport</em> parameter needs to be given (e.g. its default value of 3088).

                <p>

                <dt><code><em>sml</em></code>
                <dd>Small minimum for MTU. The default value is 16 bytes.

                <p>

                <dt><code><em>delay</em></code>
                <dd>The number of msec ATTN signals will be delayed for in order
                    to circumvent a VM/SP bug causing SIO timeout errors.
                    Override the default of 0, e.g. with 200 or or some smaller value
                    for faster Hercules hosts, but only when needed.

                <p>

                <dt><code><em>FICON</em></code>
                <dd>The keyword FICON will cause a Fibre channel CTC (i.e. a FCTC device) to be emulated.
            </dl>
        </dl> <!-- end optional CTCE parameters -->

        <p>
        A sample CTCE device configuration is shown below, using the previous CTCE version 1 format which is still fully supported:
        <blockquote>
            <p>
            First Hercules PC Host with IP address 192.168.1.100:
            <pre>
    0E40   CTCE  30880  192.168.1.200  30880
    0E41   CTCE  30882  192.168.1.200  30882 </pre>
            <p>
            Second Hercules PC Host with IP address 192.168.1.200:
            <pre>
    0E40   CTCE  30880  192.168.1.100  30880
    0E41   CTCE  30882  192.168.1.100  30882 </pre>
        </blockquote>
        <p>

                <p>
        Exploiting the new features of the newer CTCE version 2 format, this can be simplified omitting all port numbers
        <blockquote>
            <p>
            First Hercules PC Host with IP address 192.168.1.100:
            <pre>
    0E40   CTCE    0E40=192.168.1.200
    0E41   CTCE    0E41=192.168.1.200        </pre>
            <p>
            Second Hercules PC Host with IP address 192.168.1.200:
            <pre>
    0E40   CTCE    0E40=192.168.1.100
    0E41   CTCE    0E41=192.168.1.100        </pre>
        </blockquote>
        <p>

        <p>
        As there are <em>2</em> equal <em>ldevnum</em> - <em>rdevnum</em> pairs, this can be simplified further:
        <blockquote>
            <p>
            First Hercules PC Host with IP address 192.168.1.100:
            <pre>
    0E40.2 CTCE        =192.168.1.200        </pre>
            <p>
            Second Hercules PC Host with IP address 192.168.1.200:
            <pre>
    0E40.2 CTCE        =192.168.1.100        </pre>
        </blockquote>
        <p>

        <p>
        Showing an example of specifying a <em>rdevnum</em> using the exclusive-or operation with a small value:
        <blockquote>
            <p>
            <pre>
    0E40.4 CTCE       1=192.168.1.200        </pre>
            <p>
            The above is axactly the same as this specification:
            <pre>
    0E40   CTCE    0E41=192.168.1.200
    0E41   CTCE    0E40=192.168.1.200
    0E42   CTCE    0E43=192.168.1.200
    0E43   CTCE    0E42=192.168.1.200        </pre>
                <p>
            The above example could be used to establish a redundant pair
            of read/write CTC links, where each Hercules side uses the even
            devnum addresses for reading, and the odd ones for writing
            (or the other way around).  That way, the operating system
            definitions on each side can be identical, e.g. for a VTAM MPC CTC link :
            <pre>
    CTCATRL  VBUILD TYPE=TRL
    C0E40TRL TRLE  LNCTL=MPC,READ=(0E40,0E42),WRITE=(0E41,0E43)

    CTCALCL  VBUILD TYPE=LOCAL
    C0E40LCL PU    TRLE=C0E40TRL,XID=YES,CONNTYPE=APPN,CPCP=YES,TGP=CHANNEL</pre>
        </blockquote>
        <p>

<p><br>

<a name="PTP"></a>
    <dt><b>PTP</b> &nbsp; &nbsp; (MPCPTP/MPCPTP6 Channel to Channel link)
    <dd><p>
        A point-to-point IP connection with the TCP/IP stack of the
        host system on which Hercules is running.
        From the point of view of the guest image running in the Hercules
        machine it appears to be an MPCPTP and/or MPCPTP6 ESCON CTC link to
        another image.
        <p>

        The PTP device is a "grouped" device that requires 2 (two) device
        addresses (device numbers) to be defined per PTP group, with the
        first device of the group being an even numbered device:

            <blockquote>
            <code>0460<b>.2</b> &nbsp; PTP &nbsp;<i>[arguments]</i></code>
            </blockquote>

        <p>

        <p class="box">
        <i>
        <b>Note:</b> Refer to the discussion in the <a href=#netpriv>NETDEV</a> statement
        for important information regarding elevated privileges that <u>may</u> be required
        for networking devices.
        </i>
        </p>

        <p>
        For *nix systems, such as Linux, BSD, and OSX, you may use
        preconfigured interfaces or you may request Hercules to configure
        the interface for you.
        In the first case you must know and supply the name of the interface
        to use; in the second case the kernel supplies an interface name.
        See the <a href="herctcp.html">Hercules TCP/IP</a> page for more details.
        <p>

        <dl> <!-- begin PTP parms -->
        <dt>Required for *nix when using a preconfigured interface:

        <dd><p>
            <dl> <!-- begin Required for *nix preconfigured -->
                <dt>[<code>-x</code>/<code>--if</code>] <code><em>ifname</em></code>
                <dd><p>
                    Specifies the interface name of a TUN interface that is
                    already configured.
                    <p>
                    Specify no host names or IP addresses or other arguments as
                    the information is already configured into the interface.
                    <p>
            </dl> <!-- end Required for *nix preconfigured -->

        <dt>Required for *nix when not using a preconfigured interface,
        and for Windows:
        <dd><p>
            <dl> <!-- begin Required for both *nix not preconfigured and Windows -->
                <dt><code><em>guest1</em></code>
                <dd><p>
                    Specifies the host name or IP address of the guest
                    operating system running under Hercules.
                    <p>

                <dt><code><em>host1</em></code>
                <dd><p>
                    Specifies the host name or IP address of the host
                    (Linux or Windows) side of the point-to-point link.
                    <p>

                <dt><code><em>guest2</em></code>
                <dd><p>
                    Specifies the host name or IP address of the guest
                    operating system running under Hercules.
                    <p>

                <dt><code><em>host2</em></code>
                <dd><p>
                    Specifies the host name or IP address of the host
                    (Linux or Windows) side of the point-to-point link.
                    <p>

                <dt><code><em>guest1</em></code> and <code><em>host1</em></code>
                must both be of the same address family, i.e. both IPv4 or
                both IPv6.
                <p>

                <dt><code><em>guest2</em></code> and <code><em>host2</em></code>,
                if specified, must both be of the same address family, i.e. both
                IPv4 or both IPv6, and must not be of the same address family as
                <code><em>guest1</em></code> and <code><em>host1</em></code>.
                <p>

                <dt>If a host name is specified for <code><em>guest1</em></code>,
                and the host name can be resolved to both an IPv4 and an IPv6
                address, use either the <code>-4</code>/<code>--inet</code>
                or the <code>-6</code>/<code>--inet6</code> option to
                specify which address family should be used;
                if neither the <code>-4</code>/<code>--inet</code> nor the
                <code>-6</code>/<code>--inet6</code> option is specified,
                whichever address family the resolver returns first will
                be used.
                <p>

                <dt><code><em>host1</em></code> or <code><em>host2</em></code> can
                be followed by the prefix size expressed in CIDR notation,
                e.g. 192.168.1.1/24 or 2001:db8:3003:1::543:210f/48.
                For IPv4 the prefix size can have a value from 0 to 32;
                if not specified a value of 32 is assumed.
                For IPv6 the prefix size can have a value from 0 to 128;
                if not specified a value of 128 is assumed.
                For IPv4 the prefix size is used to produce the equivalent
                subnet mask; for example, a value of 24 produces a subnet
                mask of 255.255.255.0.
                <p>

                <dt>If <code><em>guest1</em></code>, <code><em>host1</em></code>,
                <code><em>guest2</em></code> or <code><em>host2</em></code>
                are numeric IPv6 addresses, they can be between braces,
                e.g. [2001:db8:3003:1::543:210f].
                <p>

            </dl> <!-- end Required for both *nix not preconfigured and Windows -->

            <p>

        <dt>Optional for *nix:
        <dd><p>
            If these arguments are specified, they must precede the required
            arguments.
            <p>

            <dl> <!-- begin Optional for *nix -->

                <dt><code>-t <em>size</em></code> &nbsp;&nbsp; or &nbsp; <code>--mtu <em>size</em></code>
                <dd><p>
                    where <code><em>size</em></code> is the maximum transmission
                    unit size. The default size is 1500.
                    <p>

                <dt><code>-x <em>name</em></code> &nbsp;&nbsp; or &nbsp; <code>--if <em>name</em></code>
                <dd><p>
                    Specifies the name of the TUN interface to use.
                    There is no default for <code><em>name</em></code>.
                    <p>

            </dl> <!-- end Optional for *nix -->

            <p>

        <dt>Optional for Windows:
        <dd><p>
            If these arguments are specified, they must precede the required
            arguments.
            <p>

            <dl> <!-- begin Optional for Windows -->

                <dt><code>-m <em>MAC address</em></code> &nbsp;&nbsp; or &nbsp; <code>--mac <em>MAC address</em></code>
                <dd><p>
                    where <em>'MAC address'</em> is the optional hardware address for
                    the virtual interface in the format: hh:hh:hh:hh:hh:hh. The default value
                    is '02:00:5E:nn:nn:nn' where the <i>:nn:nn:nn</i> portion is constructed
                    from the last 3 octets of the specified <code><i>guestip</i></code>.
                    <p>
                    <i>
                    <b>Note:</b> The MAC address you specify for this option MUST have the 02 locally
                    assigned MAC bit on in the first byte, must NOT have the 01 broadcast bit
                    on in the first byte, and MUST be unique as seen by all other devices on
                    your network segment. It should never, for example, be the same as the host
                    adapter MAC address specified on the <code><em>-n</em></code> parameter.
                    </i>
                    <p>

                <dt><code>-k &nbsp;<em>kernel-capture-buffer-size</em></code>
                    <dd>
                <dt><code>-i &nbsp;<em>tuntap32-i/o-buffer-size</em></code>
                <dd><p>
                    Refer to the Help file included with SoftDevLabs's
                    <a href="http://www.softdevlabs.com/ctci-win">CTCI-WIN</a> product
                    for further details and information.
                    <p>

            </dl> <!-- end Optional for Windows -->

            <p>

        <dt>Optional for both *nix and Windows:
        <dd><p>
            If these arguments are specified, they must precede the required
            arguments:
            <p>

            <dl> <!-- begin Optional for both *nix and Windows -->

                <dt><code>-n <em>name</em></code> &nbsp;&nbsp; or &nbsp; <code>--dev <em>name</em></code>
                <dd><p>
                    Specifies the name of the tunnel device to use.
                    The default for this option is the value specified
                    by the <a href="#netdev">NETDEV</a> configuration file statement.
                    <p>

                <dt><code>-4</code> &nbsp;&nbsp; or &nbsp; <code>--inet</code>
                <dd><p>
                    Indicates that when a host name is specified for
                    <code><em>guest1</em></code>, the host name must
                    resolve to an IPv4 address.

                <dt><code>-6</code> &nbsp;&nbsp; or &nbsp; <code>--inet6</code>
                <dd><p>
                    Indicates that when a host name is specified for
                    <code><em>guest1</em></code>, the host name must
                    resolve to an IPv6 address.

                <dt><code>-d</code> &nbsp;&nbsp; or &nbsp; <code>--debug</code>
                <dd><p>
                    Specifies that debugging output is to be produced on the
                    Hercules control panel. This should normally be left
                    unspecified.
                    <p>

            </dl> <!-- end Optional for both *nix and Windows -->

        </dl> <!-- end PTP parms -->

    </dl> <!-- end emulation types -->

    <p><br>

<hr width="50%"><p>

<a name="3380"></a>
<a name="ckddasd"></a>
<dt><em>CKD DASD devices</em>
<dd><p>
    The argument specifies the name of a file containing the disk CKD
    DASD image or the INET address of a Hercules <a href="shared.html">Shared Device server</a>.
    <p>

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

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

    <em><b>Note:</b> &nbsp;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.</em>
    <p>

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

    Alternatively, the argument may specify the name of a file containing
    a compressed CCKD DASD image.  The CKD driver will automatically detect
    whether the file contains a regular CKD image or a compressed CCKD
    image.
    <p>

    Refer to "<a href="hercload.html#dasdinit">Creating an empty DASD volume</a>"
    in the "Creating, formatting, and loading DASD volumes" section of the
    <a href="hercload.html">Creating DASD</a>
    web page for information on using the 'dasdinit' command/utility to
    create compressed dasd files. Refer to the
    <a href="cckddasd.html">Compressed Dasd Emulation</a>
    page for details on the actual CCKD emulation itself and additional
    information on the <a href="cckddasd.html#cckdcommand"><code>'CCKD'</code>
    initialization/tuning control file statement</a>, as well as information
    regarding the use of <a href="cckddasd.html#shadowfiles">shadow files</a>.
    <p>

    If you specify an INET address, the format is:
    <p>

    <dl> <!-- begin INET parms -->
    <dt><code><em>ip-name-or-addr</em>:<em>port</em>:<em>devnum</em></code>
    <dd><p>
        <em>ip-name-or-addr</em> specifies the internet name or address
        where the Hercules <a href="shared.html">Shared Device server</a> is running.
        <p>

        <em>port</em> specifies the port number the Shared Device server
        is listening on.  If omitted, the default is 3990.
        <p>

        <em>devnum</em> specifies the device number on the Shared
        Device server.  If omitted, the default is the current device number.
        <p>

    </dl> <!-- end INET parms -->
    <p>


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

    <dl> <!-- begin (CKD) additional DASD arguments -->

<a name="shadow"></a>
    <dt><code>sf=<em>shadow-file-filename-template</em></code>
    <dd><p>
        Shadow files are only supported for compressed dasd images.
        <p>

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

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

        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
        <p>

        For detailed information regarding shadow files and their use, please
        see the "<a href="cckddasd.html#shadowfiles">Shadow Files</a>" section
        of the <a href="cckddasd.html">Compressed Dasd Emulation</a> web page.
        <p>

    <dt><code>readonly</code>
    <dd><p>
        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.)
        <p>
        <code>readonly</code> may be abbreviated as
        <code>rdonly</code> or <code>ro</code>
        <p>

    <dt><code>fakewrite</code>
    <dd><p>
        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.
        <p>
        Please also note the <code>fakewrite</code> option is only valid when
        the <code>readonly</code> option is also specified. That is to say,
        regardless of whether the host dasd image file is actually read/only
        or read/write, specifying the <code>fakewrite</code> option without
        the <code>readonly</code> option also being specified, is invalid.
        The <code>fakewrite</code> option should always be considered to be
        a <i><u>subset</u></i> of the <code>readonly</code> option.
        <p>
        <code>fakewrite</code> may be abbreviated as
        <code>fakewrt</code> or <code>fw</code>
        <p>

    <dt><code>[no]lazywrite</code>
    <dt><code>[no]fulltrackio</code>
    <dd><p>
        These options have been deprecated. They are still accepted, but they
        do absolutely nothing.
        <p>
        <code>fulltrackio</code> may be abbreviated as
        <code>fulltrkio</code> or <code>ftio</code>
        <p>

<a name="cu"></a>
    <dt><code>cu=<em>type</em></code>
    <dd><p>
        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 sole purpose is to force a particular control unit type
        to be indicated in the data returned by SENSE ID and similar CCW's.
        <p>
        The default value depends on the device type:
        <blockquote>
            <table border=1 cellpadding=3>
            <tr align="center"><th>&nbsp;Dasd Device type&nbsp;</th><th>&nbsp;Default 'cu=' Control Unit Type&nbsp;</th></tr>
            <tr align="center"><td>2311</td><td>2841</td></tr>
            <tr align="center"><td>2314</td><td>2314</td></tr>
            <tr align="center"><td>3330 3340<br>3350 3375<br>3380</td><td>3880</td></tr>
            <tr align="center"><td>3390</td><td>3990</td></tr>
            <tr align="center"><td>9345</td><td>9343</td></tr>
            </table>
        </blockquote>
        <p>
        Other values which may be specified for 3390 dasd device types are
        <code>3990-3</code> and <code>3990-6</code>.
        <p>
        For modern "z" operating systems such as z/OS and z/VM using 3390 dasds,
        <code>cu=3990-6</code> should be specified. For older legacy type operating
        systems, <code>cu=3990-3</code> is probably what should be specified instead.
        The default control unit type of <code>cu=3990</code> is rarely what you actually want.
        <p>
        <i>Please note</i> that this option must be specified in lower case "<code>cu=</code>".
        Using upper case "<code>CU=</code>" will not be recognized and will result in an error.
        <p>

<a name="ckdser"></a>
    <dt><code>ser=<em>nnnnnnnnnnnn</em></code>
    <dd><p>
        Defines an optional overriding 12-digit serial number to be used for this device.
        The specified serial number will be used regardless of whatever
        permanent or randomly assigned serial number the device might have (if any).
        <p>

    </dl> <!-- end (CKD) additional DASD arguments  -->
    <p>

<hr width="50%"><p>

<a name="3370"></a>
<a name="fbadasd"></a>
<dt><em>FBA DASD devices</em>
<dd><p>
    The file consists of fixed length 512-byte records,
    each of which represents one physical block of the emulated disk.
    <p>

    The first argument specifies the name of a file which contains
    the FBA DASD image or the INET address of a Hercules
    <a href="shared.html">Shared Device server</a>.
    <p>

    If you specify a Shared Device server INET address, the format
    of the filename is:
    <p>

    <dl> <!-- begin INET parms -->

    <dt><code><em>ip-name-or-addr</em>:<em>port</em>:<em>devnum</em></code>
    <dd><p>

        <em>ip-name-or-addr</em> specifies the internet name or address
        where the Hercules Shared Device server is running.
        <p>

        <em>port</em> specifies the port number the Shared Device server
        is listening on.  If omitted, the default is 3990.
        <p>

        <em>devnum</em> specifies the device number on the Shared
        Device server.  If omitted, the default is the current device number.

    </dl> <!-- end INET parms -->
    <p>

    To allow access to a minidisk within a full-pack FBA DASD image
    file, <i><u>normal NON-compressed FBA dasds</u></i> also support
    two additional arguments after the file name:
    <p>

    <dl> <!-- begin FBA DASD arguments -->

    <dt><code><em>origin</em></code>
    <dd><p>
        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.
        <p>

    <dt><code><em>numblks</em></code>
    <dd><p>
        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 <b>*</b> asterisk,
        then the minidisk continues to the end of the DASD image file.
        <p>

    </dl> <!-- end FBA DASD arguments -->
    <p>

    <i><u>Compressed CFBA dasds</u></i> also support an additional optional argument:
    <p>

    <dl> <!-- begin (CFBA) additional DASD arguments -->

    <dt><code>sf=<em>shadow-file-name</em></code>
    <dd><p>
        The handling of shadow files for compressed CFBA devices is identical
        as that for CCKD devices. Please refer to the
        <a href="#shadow">preceding CKD section</a>
        for information regarding use of the <code>sf=</code> shadow file option.
        <p>

    </dl> <!-- end (CFBA) additional DASD arguments  -->
    <p>

<hr width="50%"><p>

<a name="2703"></a>
<dt><em>Communication Line - BSC</em>
<dd><p>
    (Preliminary 2703 BSC Support)
    <p>

    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 line emulates a point-to-point
    BSC link. There is no point-to-multipoint handling.
    <p>

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

    The following options define the line emulation behaviour:
    <p>

    <dl> <!-- begin Communication Adapter parms -->

<a name="dial"></a>
    <dt><code>DIAL=IN &#124; OUT &#124; INOUT &#124; NO</code>
    <dd><p>
        Specifies call direction (if any). If <code>DIAL=NO</code> 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 <code>DIAL=IN&#124;INOUT</code>
        is specified, a TCP incoming call is accepted ONLY if an 'ENABLE' CCW is currently
        executing on the device. If <code>DIAL=OUT</code>, the 'ENABLE' CCW is rejected.
        When <code>DIAL=IN&#124;INOUT</code> 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.
        <p>

    <dt><code>LHOST=<em>hostname</em> &#124; <em>ip address</em> &#124; *</code>
    <dd><p>
        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 <code>DIAL=OUT</code> is specified has no effect.
        <p>

    <dt><code>LPORT=<em>service name</em> &#124; <em>port number</em></code>
    <dd><p>
        Specifies the TCP port for which to listen to incoming TCP calls. This
        value is mandatory for <code>DIAL=IN&#124;INOUT&#124;NO</code>. It is ignored for <code>DIAL=OUT</code>.
        <p>

    <dt><code>RHOST=<em>hostname</em> &#124; <em>ip address</em></code>
    <dt><code>RPORT=<em>service name</em> &#124; <em>port number</em></code>
    <dd><p>
        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 <code>DIAL=NO</code>
        is specified. It is ignored for other <code>DIAL</code> values.
        <p>

    </dl> <!-- end Communication Adapter parms -->

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

    <dl> <!-- begin Communication Adapter tuning options -->

    <dt><code>RTO=0 &#124; -1 &#124; <em>nnn</em> &#124; 3000</code>
    <dd><p>
        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.
        <p>

    <dt><code>PTO=0 &#124; -1 &#124; <em>nnn</em> &#124; 3000</code>
    <dd><p>
        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.
        <p>

    <dt><code>ETO=0 &#124; -1 &#124; <em>nnn</em> &#124; 10000</code>
    <dd><p>
        Specifies the number of milliseconds before terminating an ENABLE operation on a timeout.
        the timeout applies when <code>DIAL=NO&#124;IN&#124;INOUT</code> is specified, the outgoing TCP call
        fails (<code>DIAL=NO</code>) and there is no previously or currently established TCP connection
        for this line. When <code>DIAL=NO</code> is specified, the timeout defaults to 10 seconds.
        For <code>DIAL=IN&#124;INOUT</code>, the timeout defaults to -1.
        <p>

    </dl> <!-- end Communication Adapter tuning options -->

<dt><em>Communication Line - TTY</em>
<dd><p>
    (Preliminary 2703 TELE2 TTY Support)
    <p>
    Describes a 2703 Telegraph Terminal Control Type II (TTY 33/35) stop/start line,
    providing access to the Host OS via a standard TELNET client. To the host OS
    the line emulates an asynchronous TELE2 connection.  The communication is
    emulated over a TELNET connection.
    <p>
    The following options define the line emulation behaviour:
    <p>

    <dl> <!-- begin Communication Adapter parms -->

    <dt><code>LPORT=<em>port number</em></code>
    <dd><p>
        Specifies the TCPIP port to listen on for incoming TCP calls.
        <p>

    <dt><code>DIAL=IN</code>
    <dd><p>
        Specifies that this line is for in-bound calls. Required.
        <p>

    <dt><code>TERM=TTY</code>
    <dd><p>
        Specifies that this definition is for a TTY port. Required
        <p>

    </dl> <!-- end Communication Adapter parms -->

<dt><em>Additional 2703 Communication Line options</em>
<dd><p>
    The following are some additional options that may also be specified
    for 2703 devices:
    <p>

    <dl> <!-- begin Addtional 2703 options -->

    <dt><code>APPEND=<em>hh..</em>.</code>
    <dt><code>PREPEND=<em>hh...</em></code>
    <dd><p>
        Specifies up to four bytes (in S/370 channel format, not ASCII)
        to be prepended or appended to input line data received
        from terminals before they are sent to the guest OS. Typical use is to
        add Circle D and C around each input transmission (2741's for APL\360).
        <p>

    <dt><code>BINARY=NO &#124; YES</code>
    <dd><p>
        Negotiate to telnet binary mode if TERM=RXVT4APL.
        <p>

    <dt><code>BS=DUMB</code>
    <dt><code>BREAK=DUMB</code>
    <dd><p>
        Backspace and break key handling option.
        <p>
        When using windows telnet it is recommended
        to always use BS=DUMB and BREAK=DUMB.
        <p>

    <dt><code>CODE=EBCD &#124; CORR &#124; NONE</code>
    <dd><p>
        Specify code=ebcd for EBCD, code=corr for correspondence code,
        or code=none to disable all translation.  The code= option applies to
        2741 mode only.
        <p>

    <dt><code>CRLF=YES &#124; NO</code>
    <dd><p>
        Option to map 2741 NL to TTY CRLF sequence.
        <p>

    <dt><code>CRLF2CR=YES &#124; NO</code>
    <dd><p>
        Remove LF that immediately follow CR.
        <p>

    <dt><code>EOL=<em>hh</em></code>
    <dd><p>
        Specifies the ASCII byte value that, when received, marks the
        end of the input line. The default is EOL=0D.
        <p>

    <dt><code>ISKIP=<em>hh...</em></code>
    <dd><p>
        Specifies up to four ASCII bytes that are to be suppressed
        during input processing.
        <p>

    <dt><code>KA=NO &#124; <em>(idle,intv,count)</em></code>
    <dd><p>
        Defines the TCP/IP keepalive settings for this line's connections.
        Refer the the <a href="#CONKPALV">CONKPALV</a> statement for details.
        <p>

    <dt><code>LNCTL=TELE2 &#124; IBM1 &#124; BSC</code>
    <dd><p>
        Specifies the type of communications line being defined.
        <p>
        For asynchronous communications lines specify LNCTL=TELE2 if TERM=TTY
        or LNCTL=IBM1 if TERM=2741. For binary synchronous (BSC) lines
        specify LNCTL=BSC.
        <p>

    <dt><code>SKIP=<em>hh...</em></code>
    <dd><p>
        Specifies "garbage" code points (either byte-reversed ASCII for
        TERM=TTY or correspondence code/EBCD for TERM=2741) that are to be
        suppressed in output processing, thereby allowing distinct lists
        to be used for different terminal types.
        <p>

    <dt><code>SENDCR=NO &#124; YES</code>
    <dd><p>
        Send CR back to terminal when input line received.
        <p>

    <dt><code>SWITCHED=IN &#124; OUT &#124; INOUT &#124; NO</code>
    <dd><p>
        Switched is just a synonym for the <a href="#DIAL">DIAL</a> option.
        <p>

    <dt><code>TERM=TTY &#124; 2741 &#124; RXVT4APL</code>
    <dd><p>
        Specifies the terminal type. Use RXVT4APL for 8-bit and character
        translation in 2741 mode.
        <p>

    <dt><code>UCTRANS=YES &#124; NO</code>
    <dd><p>
        Enable automatic translation to uppercase.
        <p>

    </dl> <!-- end Addtional 2703 options -->


</dl> <!-- end Arguments for each device type -->

<center><hr width=15% noshade></center>
<p>

If you have a question about Hercules, see the
<a href="hercfaq.html">Hercules Frequently-Asked Questions</a> page.

<p><center><hr width=15% noshade>
<a href="##" onclick="history.go(-1)"><img src="images/back.gif" border=0 alt="back"></a>
<p class="lastupd"><script language="Javascript">
document.write( "Last updated " + document.lastModified + "" );
</script></p>
</body>
</html>