mirror of
https://github.com/SDL-Hercules-390/hyperion.git
synced 2026-04-13 07:25:22 +02:00
5212 lines
233 KiB
HTML
5212 lines
233 KiB
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 Listening port for 3270 device connections
|
|
<a href="#SYSGPORT">SYSGPORT</a> 3278 Listening port for SYSG device connections
|
|
<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 # 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 S/370 | ESA/390 | ESAME | <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 <u>ENABLE</u> | DISABLE</code> <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> (or do not specify anything
|
|
at all) if your guest operating system supports or expects this feature.
|
|
Set it to <code>DISABLE</code> 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 <u>ON</u> | 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 <em>[±]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> 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 <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 <u>OFF</u> | <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 <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 <i><u>3270</u></i> <i>-or-</i> <i>nnnn</i> <i>-or-</i> <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>
|
|
Note that the CNSLPORT statement will be ignored and no listening port
|
|
will be opened unless there is at least one <a href="#device_types_table">
|
|
3270 device</a> defined in your configuration.
|
|
<p>
|
|
|
|
<a name="CODEPAGE"></a>
|
|
<dt><code>CODEPAGE <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"> exclamation point</td></tr>
|
|
<tr><td style="text-align:center">[</td><td style="text-align:left"> left square bracket</td></tr>
|
|
<tr><td style="text-align:center">]</td><td style="text-align:left"> right square bracket</td></tr>
|
|
<tr><td style="text-align:center">{</td><td style="text-align:left"> left curly bracket</td></tr>
|
|
<tr><td style="text-align:center">}</td><td style="text-align:left"> right curly bracket</td></tr>
|
|
<tr><td style="text-align:center">|</td><td style="text-align:left"> solid vertical bar</td></tr>
|
|
<tr><td style="text-align:center">¦</td><td style="text-align:left"> broken vertical bar</td></tr>
|
|
<tr><td style="text-align:center">\</td><td style="text-align:left"> backslash</td></tr>
|
|
<tr><td style="text-align:center">¬</td><td style="text-align:left"> logical not</td></tr>
|
|
<tr><td style="text-align:center">^</td><td style="text-align:left"> caret / circumflex</td></tr>
|
|
<tr><td style="text-align:center">_</td><td style="text-align:left"> underscore</td></tr>
|
|
<tr><td style="text-align:center">`</td><td style="text-align:left"> grave accent</td></tr>
|
|
<tr><td style="text-align:center">~</td><td style="text-align:left"> tilde</td></tr>
|
|
<tr><td style="text-align:center">¢</td><td style="text-align:left"> cent</td></tr>
|
|
<tr><td style="text-align:center">£</td><td style="text-align:left"> pound</td></tr>
|
|
<tr><td style="text-align:center">¤</td><td style="text-align:left"> currency sign</td></tr>
|
|
<tr><td style="text-align:center">¥</td><td style="text-align:left"> yen</td></tr>
|
|
<tr><td style="text-align:center">§</td><td style="text-align:left"> section sign</td></tr>
|
|
<tr><td style="text-align:center">¶</td><td style="text-align:left"> pilcrow/paragraph</td></tr>
|
|
<tr><td style="text-align:center">©</td><td style="text-align:left"> copyright symbol</td></tr>
|
|
<tr><td style="text-align:center">®</td><td style="text-align:left"> registered trademark</td></tr>
|
|
<tr><td style="text-align:center">ª</td><td style="text-align:left"> feminine ordinal indicator</td></tr>
|
|
<tr><td style="text-align:center">°</td><td style="text-align:left"> degree</td></tr>
|
|
<tr><td style="text-align:center">º</td><td style="text-align:left"> masculine ordinal indicator</td></tr>
|
|
<tr><td style="text-align:center">±</td><td style="text-align:left"> plus-minus</td></tr>
|
|
<tr><td style="text-align:center">µ</td><td style="text-align:left"> mu/micro</td></tr>
|
|
<tr><td style="text-align:center">¿</td><td style="text-align:left"> inverted question mark</td></tr>
|
|
<tr><td style="text-align:center">×</td><td style="text-align:left"> multiplication sign</td></tr>
|
|
<tr><td style="text-align:center">÷</td><td style="text-align:left"> obelus/divide sign</td></tr>
|
|
|
|
</table>
|
|
</blockquote>
|
|
|
|
<p>
|
|
|
|
<a name="CONKPALV"></a>
|
|
<dt><code>CONKPALV <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> 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>
|
|
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> 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 <u>0</u> | 1 | 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 <u>0586</u> | <em>xxxx</em> | <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 <u>000001</u> | <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 <u>FD</u> | <em>xx</em> [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 <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 ("). 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 ""
|
|
<p>
|
|
|
|
<a name="DEVTMAX"></a>
|
|
<dt><code>DEVTMAX -1 | 0 | <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> 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 <u>DISABLE</u> | ENABLE [ECHO | <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> 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 YES | <u>NO</u> | LEVEL <em>nn</em> [ TRAP | 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 [<em>nn</em>*]<u>CP</u>|IL|AP|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 ENABLE | DISABLE | QUERY <em>facility</em> <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> 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> 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> 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 <em>nn</em></code> <i>(deprecated; unsupported)</i>
|
|
<dt><code>TODPRIO <em>nn</em></code> <i>(deprecated; unsupported)</i>
|
|
<dt><code>DEVPRIO <em>nn</em></code> <i>(deprecated; unsupported)</i>
|
|
<dt><code>CPUPRIO <em>nn</em></code> <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 PORT <em>nnnn</em> [[NOAUTH] | [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> 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> 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 ROOT <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 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 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 <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 <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 <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 <u>OFF</u> | <u>DISABLE</u> | ON | 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 <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 <u>TIMESTAMP</u> | NOTIMESTAMP | DATESTAMP | <u>NODATESTAMP</u> | </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 <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 BASIC | <u>1</u> | <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 <em>nnnn</em> |
|
|
<em>nnn</em>K |
|
|
<em>nnn</em>M |
|
|
<em>nnn</em>G |
|
|
<em>nnn</em>T |
|
|
<em>nnn</em>P |
|
|
<em>nnn</em>E</code>
|
|
<dd><p>
|
|
Specifies the main storage size in megabytes, where
|
|
<code><em>nnnn</em></code> is a decimal number. Or,
|
|
<code><em>nnnM</em></code> where <code><em>M</em></code>
|
|
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 <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 <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 <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 <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 DISALLOW | DISABLE | <u>ALLOW</u> | <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>|<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>|<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 <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 <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 <u>DEFAULT</u> | OS/390 | z/OS
|
|
| VM | z/VM | VSE | z/VSE | LINUX
|
|
| OpenSolaris | QUIET | 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 z/VM</br>
|
|
OSTAILOR +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 <u>FULLPATH</u>|NAMEONLY RATE=<u>SLOW</u>|FAST|<em>nnn</em> MSGCOLOR=<u>NO</u>|DARK|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> <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 <u>SLOW</u> | FAST | <em>nn</em></code> <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 <em>"title-string"</em></code> <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 <u>RESTRICTED</u> | 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: 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 <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 <u>NO</u> | YES | <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>
|
|
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> 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 <u>DISABLE</u> | ENABLE [DIAG8 | <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> 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 <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 <em>yyyy</em> [±<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 <i><u>NO</u></i> <i>-or-</i> <i>3278</i> <i>-or-</i> <i>nnnn</i> <i>-or-</i> <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>
|
|
Note that the SYSGPORT statement will be ignored and no listening port
|
|
will be opened unless your configuration has a <a href="#device_types_table">
|
|
SYSG device</a> defined.
|
|
<p>
|
|
|
|
<a name="TIMERINT"></a>
|
|
<dt><code>TIMERINT DEFAULT | <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> 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 <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 [<u>TRADITIONAL</u> | REGSFIRST | NOREGS] [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 ±<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 <em>nnnn</em> |
|
|
<em>nnn</em>M |
|
|
<em>nnn</em>G |
|
|
<em>nnn</em>T |
|
|
<em>nnn</em>P |
|
|
<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> where <code><em>M</em></code>
|
|
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 ±<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 ±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 # 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>"BAR"</em> then <em>$(FOO)</em> will be substituted with the
|
|
string <em>"BAR"</em>;. Symbol names are case sensitive.
|
|
|
|
<h5>Example</h5><code><pre>
|
|
DEFSYM TAPEDIR "/home/hercules/tapes"
|
|
|
|
...
|
|
|
|
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> CUU </TD><TD> (3 digits device number, upper case hexadecimal digits)</TD></TR>
|
|
<TR><TD><LI> CCUU </TD><TD> (4 digits device number, upper case hexadecimal digits)</TD></TR>
|
|
<TR><TD><LI> DEVN </TD><TD> (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 "BAR", then $$(FOO) will remain "$$(FOO)" while $$$(FOO)
|
|
will become "$BAR".
|
|
<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%"> </TD>
|
|
<TD ALIGN="CENTER" VALIGN="BASELINE" WIDTH="6%"> </TD>
|
|
<TD ALIGN="LEFT" VALIGN="BASELINE" WIDTH="15%"> </TD>
|
|
<TD ALIGN="LEFT" VALIGN="BASELINE" WIDTH="67%"> </TD>
|
|
</TR>
|
|
<TR>
|
|
<TD ALIGN="RIGHT" VALIGN="BASELINE" WIDTH="11%">-20 to -16</TD>
|
|
<TD ALIGN="CENTER" VALIGN="BASELINE" WIDTH="6%"> </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%"> </TD>
|
|
<TD ALIGN="CENTER" VALIGN="BASELINE" WIDTH="6%"> </TD>
|
|
<TD ALIGN="LEFT" VALIGN="BASELINE" WIDTH="15%"> </TD>
|
|
<TD ALIGN="LEFT" VALIGN="BASELINE" WIDTH="67%"> </TD>
|
|
</TR>
|
|
<TR>
|
|
<TD ALIGN="RIGHT" VALIGN="BASELINE" WIDTH="11%">-15 to -9</TD>
|
|
<TD ALIGN="CENTER" VALIGN="BASELINE" WIDTH="6%"> </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%"> </TD>
|
|
<TD ALIGN="CENTER" VALIGN="BASELINE" WIDTH="6%"> </TD>
|
|
<TD ALIGN="LEFT" VALIGN="BASELINE" WIDTH="15%"> </TD>
|
|
<TD ALIGN="LEFT" VALIGN="BASELINE" WIDTH="67%"> </TD>
|
|
</TR>
|
|
<TR>
|
|
<TD ALIGN="RIGHT" VALIGN="BASELINE" WIDTH="11%">-8 to -1</TD>
|
|
<TD ALIGN="CENTER" VALIGN="BASELINE" WIDTH="6%"> </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%"> </TD>
|
|
<TD ALIGN="CENTER" VALIGN="BASELINE" WIDTH="6%"> </TD>
|
|
<TD ALIGN="LEFT" VALIGN="BASELINE" WIDTH="15%"> </TD>
|
|
<TD ALIGN="LEFT" VALIGN="BASELINE" WIDTH="67%"> </TD>
|
|
</TR>
|
|
<TR>
|
|
<TD ALIGN="RIGHT" VALIGN="BASELINE" WIDTH="11%">0 to +7</TD>
|
|
<TD ALIGN="CENTER" VALIGN="BASELINE" WIDTH="6%"> </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%"> </TD>
|
|
<TD ALIGN="CENTER" VALIGN="BASELINE" WIDTH="6%"> </TD>
|
|
<TD ALIGN="LEFT" VALIGN="BASELINE" WIDTH="15%"> </TD>
|
|
<TD ALIGN="LEFT" VALIGN="BASELINE" WIDTH="67%"> </TD>
|
|
</TR>
|
|
<TR>
|
|
<TD ALIGN="RIGHT" VALIGN="BASELINE" WIDTH="11%">+8 to +14</TD>
|
|
<TD ALIGN="CENTER" VALIGN="BASELINE" WIDTH="6%"> </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%"> </TD>
|
|
<TD ALIGN="CENTER" VALIGN="BASELINE" WIDTH="6%"> </TD>
|
|
<TD ALIGN="LEFT" VALIGN="BASELINE" WIDTH="15%"> </TD>
|
|
<TD ALIGN="LEFT" VALIGN="BASELINE" WIDTH="67%"> </TD>
|
|
</TR>
|
|
<TR>
|
|
<TD ALIGN="RIGHT" VALIGN="BASELINE" WIDTH="11%">+15 to +19</TD>
|
|
<TD ALIGN="CENTER" VALIGN="BASELINE" WIDTH="6%"> </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>
|
|
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%"> </TD>
|
|
<TD ALIGN="CENTER" VALIGN="BASELINE" WIDTH="6%"> </TD>
|
|
<TD ALIGN="LEFT" VALIGN="BASELINE" WIDTH="15%"> </TD>
|
|
<TD ALIGN="LEFT" VALIGN="BASELINE" WIDTH="67%"> </TD>
|
|
</TR>
|
|
<TR>
|
|
<TD ALIGN="RIGHT" VALIGN="BASELINE" WIDTH="11%">1</TD>
|
|
<TD ALIGN="CENTER" VALIGN="BASELINE" WIDTH="6%"> </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%"> </TD>
|
|
<TD ALIGN="CENTER" VALIGN="BASELINE" WIDTH="6%"> </TD>
|
|
<TD ALIGN="LEFT" VALIGN="BASELINE" WIDTH="15%"> </TD>
|
|
<TD ALIGN="LEFT" VALIGN="BASELINE" WIDTH="67%"> </TD>
|
|
</TR>
|
|
<TR>
|
|
<TD ALIGN="RIGHT" VALIGN="BASELINE" WIDTH="11%">2</TD>
|
|
<TD ALIGN="CENTER" VALIGN="BASELINE" WIDTH="6%"> </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%"> </TD>
|
|
<TD ALIGN="CENTER" VALIGN="BASELINE" WIDTH="6%"> </TD>
|
|
<TD ALIGN="LEFT" VALIGN="BASELINE" WIDTH="15%"> </TD>
|
|
<TD ALIGN="LEFT" VALIGN="BASELINE" WIDTH="67%"> </TD>
|
|
</TR>
|
|
<TR>
|
|
<TD ALIGN="RIGHT" VALIGN="BASELINE" WIDTH="11%">3</TD>
|
|
<TD ALIGN="CENTER" VALIGN="BASELINE" WIDTH="6%"> </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%"> </TD>
|
|
<TD ALIGN="CENTER" VALIGN="BASELINE" WIDTH="6%"> </TD>
|
|
<TD ALIGN="LEFT" VALIGN="BASELINE" WIDTH="15%"> </TD>
|
|
<TD ALIGN="LEFT" VALIGN="BASELINE" WIDTH="67%"> </TD>
|
|
</TR>
|
|
<TR>
|
|
<TD ALIGN="RIGHT" VALIGN="BASELINE" WIDTH="11%">4</TD>
|
|
<TD ALIGN="CENTER" VALIGN="BASELINE" WIDTH="6%"> </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%"> </TD>
|
|
<TD ALIGN="CENTER" VALIGN="BASELINE" WIDTH="6%"> </TD>
|
|
<TD ALIGN="LEFT" VALIGN="BASELINE" WIDTH="15%"> </TD>
|
|
<TD ALIGN="LEFT" VALIGN="BASELINE" WIDTH="67%"> </TD>
|
|
</TR>
|
|
<TR>
|
|
<TD ALIGN="RIGHT" VALIGN="BASELINE" WIDTH="11%">5</TD>
|
|
<TD ALIGN="CENTER" VALIGN="BASELINE" WIDTH="6%"> </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%"> </TD>
|
|
<TD ALIGN="CENTER" VALIGN="BASELINE" WIDTH="6%"> </TD>
|
|
<TD ALIGN="LEFT" VALIGN="BASELINE" WIDTH="15%"> </TD>
|
|
<TD ALIGN="LEFT" VALIGN="BASELINE" WIDTH="67%"> </TD>
|
|
</TR>
|
|
<TR>
|
|
<TD ALIGN="RIGHT" VALIGN="BASELINE" WIDTH="11%">6</TD>
|
|
<TD ALIGN="CENTER" VALIGN="BASELINE" WIDTH="6%"> </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%"> </TD>
|
|
<TD ALIGN="CENTER" VALIGN="BASELINE" WIDTH="6%"> </TD>
|
|
<TD ALIGN="LEFT" VALIGN="BASELINE" WIDTH="15%"> </TD>
|
|
<TD ALIGN="LEFT" VALIGN="BASELINE" WIDTH="67%"> </TD>
|
|
</TR>
|
|
<TR>
|
|
<TD ALIGN="RIGHT" VALIGN="BASELINE" WIDTH="11%">7</TD>
|
|
<TD ALIGN="CENTER" VALIGN="BASELINE" WIDTH="6%"> </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>
|
|
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) devtype</em> [ <em>arguments</em> ] [ <em># comments...</em> ] </code>
|
|
</blockquote>
|
|
<p>
|
|
|
|
where the generic syntax for device numbers is
|
|
<code>[n:]CCUU[,CCUU][-CCUU][.nn][...]</code>
|
|
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>
|
|
<code>1:0400-040F 3270</code><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 # 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%>
|
|
|
|
</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>
|
|
<a href="#COMM"><i>many</i></a>
|
|
</td>
|
|
<td>
|
|
Communication and Channel-to-Channel devices
|
|
</td>
|
|
<td>
|
|
<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> (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> (-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> <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= <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>: 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: 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: 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= <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>: 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: 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: 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: 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> <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= <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= <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= <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> <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> <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 '|' 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):
|
|
<a href="#AWS">AWS</a>,
|
|
<a href="#HET">HET</a>,
|
|
<a href="#FAKETAPE">FakeTape</a>,
|
|
<a href="#OMA">Optical Media Attach (OMA)</a>, and
|
|
<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> (<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>|<em>0</em></code>
|
|
<dt><code>IDRC=<em><u><b>1</b></u></em></code>|<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> 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>|<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>|<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> for best compression.
|
|
The default is <code>4</code>.
|
|
<p>
|
|
|
|
<dt><code><u>CHUNKSIZE=<em><b>65535</b></em></u></code>
|
|
| <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> 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>
|
|
| <code>MAXSIZE</code>=<i>nnn</i>
|
|
| <code>MAXSIZE<b>K</b></code>=<i>nnn</i>
|
|
| <code>MAXSIZE<b>M</b></code>=<i>nnn</i>
|
|
| <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. 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>
|
|
| <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 "<code><b>/dev/nst0</b></code>" <i>(for Linux or
|
|
Windows)</i> or "<code><b>\\.\Tape0</b></code>" <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> (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> QETH <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 OSA <i>[arguments...]</i></code><br>
|
|
<code>0600.3 OSD <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 <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 <em>address</em></code>
|
|
<dt><code>ipaddr <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 <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 <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 <em>address</em></code>
|
|
<dt><code>ipaddr6 <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 <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 <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 <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> (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> LCS <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> or <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> or <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> or <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> 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 | SEC | 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> 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 pp <i> 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 pp <i> nnn.nnn.nnn.nnn ...</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> (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> CTCI <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> or <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 <em>kernel-capture-buffer-size</em></code>
|
|
<dd>
|
|
<dt><code>-i <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> or <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> or <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> or <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> (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> 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>
|
|
<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> (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> PTP <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> or <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> or <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> or <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 <em>kernel-capture-buffer-size</em></code>
|
|
<dd>
|
|
<dt><code>-i <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> or <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> or <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> or <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> or <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> 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> Dasd Device type </th><th> Default 'cu=' Control Unit Type </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 | OUT | INOUT | 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|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|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> | <em>ip address</em> | *</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> | <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|INOUT|NO</code>. It is ignored for <code>DIAL=OUT</code>.
|
|
<p>
|
|
|
|
<dt><code>RHOST=<em>hostname</em> | <em>ip address</em></code>
|
|
<dt><code>RPORT=<em>service name</em> | <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 | -1 | <em>nnn</em> | 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 | -1 | <em>nnn</em> | 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 | -1 | <em>nnn</em> | 10000</code>
|
|
<dd><p>
|
|
Specifies the number of milliseconds before terminating an ENABLE operation on a timeout.
|
|
the timeout applies when <code>DIAL=NO|IN|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|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 | 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 | CORR | 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 | NO</code>
|
|
<dd><p>
|
|
Option to map 2741 NL to TTY CRLF sequence.
|
|
<p>
|
|
|
|
<dt><code>CRLF2CR=YES | 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 | <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 | IBM1 | 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 | YES</code>
|
|
<dd><p>
|
|
Send CR back to terminal when input line received.
|
|
<p>
|
|
|
|
<dt><code>SWITCHED=IN | OUT | INOUT | NO</code>
|
|
<dd><p>
|
|
Switched is just a synonym for the <a href="#DIAL">DIAL</a> option.
|
|
<p>
|
|
|
|
<dt><code>TERM=TTY | 2741 | RXVT4APL</code>
|
|
<dd><p>
|
|
Specifies the terminal type. Use RXVT4APL for 8-bit and character
|
|
translation in 2741 mode.
|
|
<p>
|
|
|
|
<dt><code>UCTRANS=YES | 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>
|