mirror of
https://github.com/SDL-Hercules-390/hyperion.git
synced 2026-04-25 13:06:40 +02:00
781 lines
40 KiB
HTML
781 lines
40 KiB
HTML
<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 3.0//EN" "html.dtd">
|
|
<HTML>
|
|
<HEAD><TITLE>
|
|
Hercules Version 2: Configuration File</TITLE>
|
|
<LINK REL=STYLESHEET TYPE="text/css" HREF="hercules.css">
|
|
</HEAD>
|
|
<BODY BGCOLOR="#ffffcc" TEXT="#000000" LINK="#0000A0"
|
|
VLINK="#008040" ALINK="#000000">
|
|
<h1>Hercules Version 2: 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>
|
|
<blockquote><blockquote>
|
|
<table border=1><tr><td>
|
|
<pre><code>
|
|
#
|
|
# System parameters
|
|
#
|
|
|
|
CPUSERIAL 000611
|
|
CPUMODEL 3090
|
|
CPUVERID FD
|
|
MAINSIZE 64
|
|
XPNDSIZE 0
|
|
CODEPAGE default
|
|
CNSLPORT 3270
|
|
HTTPPORT 8081
|
|
HTTPROOT /usr/local/share/hercules/
|
|
DIAG8CMD disable
|
|
NUMCPU 1
|
|
NUMVEC 1
|
|
CPUPRIO 15
|
|
ARCHMODE ESA/390
|
|
LOADPARM 0120....
|
|
SYSEPOCH 1900
|
|
TZOFFSET -0500
|
|
OSTAILOR OS/390
|
|
PANRATE FAST
|
|
|
|
#
|
|
# Device definitions
|
|
#
|
|
|
|
000A 1442 adrdmprs.rdr
|
|
000C 3505 jcl.txt ascii trunc
|
|
000D 3525 pch00d.txt ascii
|
|
000E 1403 prt00e.txt
|
|
001F 3270
|
|
0120 3380 mvsv5r.120
|
|
0121 3380 mvsv5d.121
|
|
0122 3380 mvswk1.122
|
|
0140 3370 dosres.140
|
|
0141 3370 syswk1.141
|
|
0200 3270
|
|
0201 3270
|
|
0202 3270
|
|
0300 3370 sysres.300
|
|
0400 3088 CTCI /dev/tun0 1500 192.168.200.1 192.168.200.2 255.255.255.0
|
|
0401 3088 CTCI /dev/tun0 1500 192.168.200.1 192.168.200.2 255.255.255.0
|
|
0410 3088 CTCT 30880 192.168.100.2 30880 2048
|
|
0411 3088 CTCT 30881 192.168.100.2 30881 2048
|
|
0580 3420 ickdsf.ipl
|
|
0581 3420 /dev/st0
|
|
0582 3420 /cdrom/tapes/uaa196.tdf
|
|
</pre></code>
|
|
</td></tr></table>
|
|
</blockquote></blockquote>
|
|
<h3>Comment lines</h3>
|
|
<p>
|
|
Blank lines, and lines beginning with a pound sign ('#' - "hash" to
|
|
Europeans) or an asterisk, are treated as comments.
|
|
<h3>System parameters</h3>
|
|
<p>
|
|
System parameters may appear in any order but they must precede all
|
|
device records. Each system parameter must be on a separate line.
|
|
The following system parameters may be specified:
|
|
<dl>
|
|
<dt><code>CPUSERIAL <em>xxxxxx</em></code>
|
|
<dd>specifies the 6 hexadecimal digit CPU serial
|
|
number stored by the STIDP instruction
|
|
<dt><code>CPUMODEL <em>xxxx</em></code>
|
|
<dd>specifies the 4 hexadecimal digit CPU model number
|
|
stored by the STIDP instruction
|
|
<dt><code>CPUVERID <em>xx</em></code>
|
|
<dd>specifies the 2 hexadecimal digit CPU version code
|
|
stored by the STIDP instruction.
|
|
The default version code is FD when ARCHMODE S/370 or ARCHMODE ESA/390
|
|
is specified. For the ESAME architecture mode 00 is used as default.
|
|
<dt><code>MAINSIZE <em>nnnn</em></code>
|
|
<dd>specifies the main storage size in megabytes, where
|
|
<code><em>nnnn</em></code> is a decimal number
|
|
in the range is 2 to 1024
|
|
<dt><code>XPNDSIZE <em>nnnn</em></code>
|
|
<dd>specifies the expanded storage size in megabytes, where
|
|
<code><em>nnnn</em></code> is a decimal number
|
|
in the range is 0 to 1024
|
|
<dt><code>HTTPPORT <em>nnnn</em> [AUTH/NOAUTH] <em>[userid password]</em></code>
|
|
<dd>specifies the port number (in decimal) on which the HTTP server
|
|
will listen. The port number must either be 80
|
|
or within the range 1024 - 65535 inclusive. If no HTTPPORT statement is
|
|
present or an invalid port number is specified, then the HTTP server thread
|
|
will not be activated.<br>
|
|
<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.
|
|
<dt><code>HTTPROOT <em>directory</em></code>
|
|
<dd>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>).<br>
|
|
Note: Windows users of Hercules who do not have the complete Cygwin package
|
|
installed (i.e. only have the required Cygwin DLLs installed instead)
|
|
should specify this value in the form: "<tt>/cygdrive/x/pathname/</tt>"
|
|
where '<tt>x</tt>' is the Windows drive letter. For example, if the Windows
|
|
directory where the http server's files reside is
|
|
"<tt>K:\Hercules\html\</tt>", then you should specify
|
|
"<tt>/cygdrive/k/Hercules/html/</tt>"
|
|
on your <tt>HTTPROOT</tt> statement.
|
|
<dt><code>DIAG8CMD <em>disable/enable</em></code>
|
|
<dd>When set to enable, commands issued through diagnose 8 will be
|
|
executed by hercules as hercules commands. When set to disable,
|
|
commands issued through the diagnose 8 interface will be ignored.
|
|
The default is disable. Note that when this feature is enabled, systems
|
|
running under hercules can even issue host commands through the hercules
|
|
sh command. Enabling this feature may have security consequences.
|
|
<dt><code>CNSLPORT <em>nnnn</em></code>
|
|
<dd>specifies the port number (in decimal) to which tn3270 and
|
|
telnet clients will connect
|
|
<dt><code>NUMCPU <em>nn</em></code>
|
|
<dd>specifies the number of emulated CPUs.
|
|
<em>Note:</em>
|
|
Multiprocessor emulation is only available when the definition of
|
|
the compile-time variable <code>MAX_CPU_ENGINES</code>
|
|
in the file <em><b>hercules.h</b></em> has a value of more than 1.
|
|
Multiprocessor emulation works best
|
|
if your system has more than physical CPU, but you can
|
|
emulate multiple CPUs even on a uniprocessor system
|
|
and you may still achieve a small performance benefit.
|
|
There is no point in specifying NUMCPU greater than 1 unless
|
|
your operating system is able to support multiple CPUs, and
|
|
if you do not need multiprocessor emulation then setting
|
|
MAX_CPU_ENGINES to 1 at compile time may improve performance.
|
|
<dt><code>NUMVEC <em>nn</em></code>
|
|
<dd>specifies the number of emulated vector facilities. Default is one per
|
|
CPU. Only available by default in ESA/390 mode.
|
|
<dt><code>CPUPRIO <em>nn</em></code>
|
|
<dd>is only valid when Hercules is run on a *ix (Linux/Unix) host and
|
|
specifies the priority of the CPU thread. Default is a nice value of
|
|
15, which means a low priority such that I/O can be scheduled and
|
|
completed in favour of CPU cycles being burned. On Multi-CPU systems,
|
|
a real CPU can be 'dedicated' to Hercules, by giving the CPU thread a
|
|
very high dispatching priority (-20). Note that Hercules needs to be a
|
|
setuid root program to allow it to reset its dispatching priority to a
|
|
high (negative) value (ie. chown root.root hercules; chmod +s hercules)
|
|
<dt><code>LOADPARM <em>xxxxxxxx</em></code>
|
|
<dd>specifies the eight-character IPL parameter which is used
|
|
by some operating systems to select system parameters
|
|
<dt><code>SYSEPOCH <em>yyyy</em></code>
|
|
<dd>specifies the base date for the TOD clock. Use the default
|
|
value (1900) for all systems except OS/360.
|
|
OS/360 expects the base date to be 1960, but specifying this
|
|
value causes an error because OS/360 regards 2000 as an invalid
|
|
date. For OS/360, <code>SYSEPOCH 1988</code> is recommended.
|
|
This makes the year 2000 appear to be 1972.
|
|
<dt><code>TZOFFSET ±<em>hhmm</em></code>
|
|
<dd>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).
|
|
<dt><code>TODDRAG <em>nn</em></code>
|
|
<dd>specifies the TOD clock drag factor. This parameter can be used
|
|
to slow down the TOD clock by a factor of <em>nn</em>, which can
|
|
improve the performance of some operating systems which consume
|
|
significant amounts of CPU time processing timer interrupts.
|
|
<em>Use of the TODDRAG parameter is no longer recommended.</em>
|
|
<dt><code>OSTAILOR OS/390 | VM | VSE | LINUX</code>
|
|
<dd>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.
|
|
<dt><code>PANRATE SLOW | FAST | <em>nn</em></code>
|
|
<dd>specifies the panel refresh rate, in milliseconds between refreshes. SLOW
|
|
is the same as 500, and FAST is the same as 50. A value less than the
|
|
Linux system clock tick interval (10 on Intel, 1 on Alpha), or more than
|
|
5000, will be rejected. SLOW is the default.
|
|
<dt><code>ARCHMODE S/370 | ESA/390 | ESAME</code>
|
|
<dd>specifies the initial architecture mode.
|
|
Use <code>S/370</code> for OS/360, VM/370, and MVS 3.8.
|
|
Use <code>ESA/390</code> for MVS/XA, MVS/ESA, OS/390, VM/ESA, VSE/ESA,
|
|
Linux/390, and ZZSA.
|
|
Use <code>ESAME</code> for z/OS and zLinux.
|
|
When ESAME is specified, the machine will always IPL in ESA/390 mode,
|
|
but is capable of being switched into z/Architecture mode after IPL.
|
|
This is handled automatically by all z/Architecture operating systems.
|
|
<dt><code>DEVTMAX -1 | 0 | 1-n</code>
|
|
<dd>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>n</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>.
|
|
<dt><code>PGMPRDOS RESTRICTED | LICENSED</code>
|
|
<dd>specifies whether or not Hercules will run licensed program product ESA
|
|
or z/Architecture operating systems. Specify <code>RESTRICTED</code> to
|
|
make Hercules emulate an IFL (Integrated Facility for Linux) CPU. With
|
|
this specified, licensed ESA or z/Architecture OSes will refuse to
|
|
start. OS/390 and z/OS will enter an A7A wait state, with reason code 7,
|
|
at IPL time. Specify <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><b>NOTE: It is <em>YOUR</em> responsibility to comply with the terms
|
|
of your license for the software you intend to run on Hercules. If you
|
|
specify LICENSED and run a licensed operating system in violation of
|
|
that license, then don't come after the Hercules developers when the
|
|
vendor sends his lawyers after you.</b>
|
|
<p><code>RESTRICTED</code> is the default. Specifying
|
|
<code>LICENSED</code> will produce a message at Hercules startup to
|
|
remind you of your responsibility to comply with software license terms.
|
|
<dt><code>IODELAY <em>usec</em></code>
|
|
<dd>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. This problem is being pursued with IBM linux. Meanwhile,
|
|
if <code>OSTAILOR LINUX</code> is specified, then this value defaults to
|
|
<em>800</em> otherwise the value defaults to <em>0</em>.
|
|
<dt><code>CODEPAGE <em>codepage</em></code>
|
|
<dd>specifies the codepage conversion table used for ascii/ebcdic translation
|
|
"default" specifies traditional hercules codepage, "437/037",
|
|
"437/500" and "850/273" are also supported.
|
|
If no codepage is specified then the environment variable HERCULES_CP
|
|
will be inspected. The default codepage used is "default"
|
|
<dt><code>ECPS:VM YES | <em>NO</em> | n</code>
|
|
<dd>specifies whether ECPS:VM (Extended Control Program Support : Virtual Machine)
|
|
support is to be enabled. If <em>YES</em> is specified, then the support
|
|
level reported to the operating system is <em>20</em>. The purpose of
|
|
ECPS:VM is to provide to the VM/370 Operating system a set of shortcut
|
|
facilities to perform hypervisor functions (CP Assists) and virtual
|
|
machine simulation (VM Assists). Although this feature does not affect
|
|
VM Operating system products operating in XA, ESA or z/Architecture mode,
|
|
it will affect VM/370 and VM/SP products running under VM/XA, VM/ESA or z/VM.
|
|
running VM/370 and VM/SP products under VM/XA, VM/ESA or z/VM should be
|
|
done with ECPS:VM disabled. ECPS:VM should not be enabled in an AP or MP
|
|
environment. ECPS:VM has no effect on non-VM operating systems. It is
|
|
however recommended to disable ECPS:VM when running native non-VM operating
|
|
systems. If a numeric value is specified, this value will be reported
|
|
to the operating system when it issues a Store ECPS:VM level, but it
|
|
doesn't otherwise alter the ECPS:VM facility operations. This is a partial
|
|
implementation.
|
|
<dt><code>LDMOD <em>module list</em></code>
|
|
<dd>specifies additional modules that are to be loaded by the hercules dynamic loader.
|
|
The search order is 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.
|
|
<br>Multiple LDMOD statements may be used.
|
|
</dl>
|
|
<p>
|
|
A comment preceded by a pound sign may be appended to any system
|
|
parameter statement.
|
|
<h3>Device records</h3>
|
|
<p>
|
|
The remaining statements in the configuration file are device records.
|
|
There must be one device record for each I/O device or group of identical I/O devices.
|
|
The format of the device record is:
|
|
<p><code><em>devnums devtype</em> [<em>arguments</em>]</code>
|
|
<p>where:
|
|
<dl>
|
|
<dt><code><em>devnums</em></code>
|
|
<dd>is either a single <em>devnum</em>, a range of <em>devnum</em> (separated by a '-'),
|
|
a count of <em>devnum</em> (separated by a '.') or a comma separated list
|
|
of <em>devnums</em>.
|
|
Examples would be 200-210 or 0300.10 or 0400,0403 or 0100,0110-011F.
|
|
All devices defined when <em>devnums</em> specifies more than one device
|
|
have identical caracteristics (except for the device number itself).
|
|
All devices defined as a group must be defined on a single channel.
|
|
A channel is defined as a contiguous group of 256 (or hexadecimal 100) devices.
|
|
0010 and 0020 are on the same channels. 0100 and 0210 are not.
|
|
See <em>devnum</em> below for an explanation of how each device number is specified.
|
|
<dt><code><em>devnum</em></code>
|
|
<dd>is a 1 to 4 digit hexadecimal number, in the range 0000 to FFFF
|
|
(for ESA/390) or 0000 to 0FFF (for S/370). The device number uniquely
|
|
identifies each device to the operating system.
|
|
<dt><code><em>devtype</em></code>
|
|
<dd>is the device type. Valid device types are:
|
|
<p>
|
|
<table border=1 cellpadding=5 align=center>
|
|
<tr><th>Device type</th>
|
|
<th>Description</th>
|
|
<th>Emulated by</th>
|
|
</tr>
|
|
<tr><td>3270</td>
|
|
<td><a href="#loc3270">Local non-SNA 3270</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>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, 3211</td>
|
|
<td><a href="#printer">Line printers</a></td>
|
|
<td>Disk file (ASCII)</td>
|
|
</tr>
|
|
<tr><td>3410, 3420, 3480<br>3490, 9347</td>
|
|
<td><a href="#tapedev">Tape drives</a></td>
|
|
<td>Disk file, CDROM, or SCSI tape</td>
|
|
</tr>
|
|
<tr><td>3088</td>
|
|
<td><a href="#ctca">Channel-to-channel adapters</a></td>
|
|
<td>TCP socket</td>
|
|
</tr>
|
|
<tr><td>3310, 3370, 9336<br>0671</td>
|
|
<td><a href="#fbadasd">FBA direct access storage devices</a></td>
|
|
<td>Disk file</td>
|
|
</tr>
|
|
<tr><td>2311, 2314, 3330<br>3340, 3350, 3375<br>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="#comline">Communication Line</a></td>
|
|
<td>TCP Socket</td>
|
|
</tr>
|
|
</table>
|
|
<dt><code><em>arguments</em></code>
|
|
<dd>is a list of parameters whose meaning depends on the device type.
|
|
The arguments required for each class of device are shown below.
|
|
</dl>
|
|
<h3>Arguments required for each device type</h3>
|
|
<dl>
|
|
<p>
|
|
<a name="loc3270">
|
|
<dt><em>Local non-SNA 3270 devices</em>
|
|
<dd>No arguments are required for this device type. To use this
|
|
device, a tn3270 client must connect to the host Linux machine
|
|
via the port number specified in the CNSLPORT parameter.
|
|
A valid tn3270 device type, such as IBM-3278, must be used.
|
|
If your tn3270 client software allows you to specify a device
|
|
type suffix (for example, IBM-3278@001F) then you can use the
|
|
suffix to connect the client to a specific device number.
|
|
If no suffix is specified, then the client will be connected
|
|
to the first available 3270 device.
|
|
<p>
|
|
<a name="conprkb">
|
|
<dt><em>Console printer-keyboard devices</em>
|
|
<dd>No arguments are required for this device type. To use this
|
|
device, a telnet client must connect to the host Linux machine
|
|
via the port number specified in the CNSLPORT parameter.
|
|
If your telnet client software allows you to specify a device
|
|
type suffix (for example, ansi@0009) then you can use the
|
|
suffix to connect the client to a specific device number.
|
|
If no suffix is specified, then the client will be connected
|
|
to the first available 1052 or 3215 device. One optional argument
|
|
may be specified: <code>noprompt</code>, if specified, will remove
|
|
the message at the console prompting for input.
|
|
<p>
|
|
<a name="cardrdr">
|
|
<dt><em>Card reader devices</em>
|
|
<dd>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>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.
|
|
<dt><code>eof</code>
|
|
<dd>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.
|
|
<dt><code>intrq</code>
|
|
<dd>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.
|
|
<dt><code>multifile</code>
|
|
<dd>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.
|
|
<dt><code>ebcdic</code>
|
|
<dd>specifies that the file contains fixed length 80-byte EBCDIC
|
|
records with no line-end delimiters.
|
|
<dt><code>ascii</code>
|
|
<dd>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.
|
|
<dt><code>trunc</code>
|
|
<dd>specifies, for ASCII files, that lines longer than 80
|
|
characters are truncated instead of producing a unit check
|
|
error.
|
|
<dt><code>autopad</code>
|
|
<dd>specifies, for EBCDIC files, that the file is automatically
|
|
padded to a multiple of 80 bytes if necessary.
|
|
</dl>
|
|
<p>
|
|
<a name="cardpch">
|
|
<dt><em>Card punch devices</em>
|
|
<dd>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>ascii</code>
|
|
<dd>specifies that the file will be written as variable length
|
|
lines of ASCII characters delimited by line feeds or
|
|
carriage return line feed sequences at the end of each line.
|
|
Trailing blanks are removed from each line.
|
|
If the <code>ascii</code> argument is not specified, the
|
|
file is written as fixed length 80-byte EBCDIC records with
|
|
no line-end delimiters.
|
|
<dt><code>crlf</code>
|
|
<dd>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.
|
|
</dl>
|
|
<p>
|
|
<a name="printer">
|
|
<dt><em>Line printer devices</em>
|
|
<dd>The argument specifies the name of a file to which the printer
|
|
output will be written. The output is written in the form of
|
|
variable length lines of ASCII characters delimited by line
|
|
feeds or by carriage return line feed sequences. Trailing
|
|
blanks are removed from each line. Carriage control characters
|
|
are translated to blank lines or ASCII form feed characters.
|
|
If the file exists it will be overwritten.
|
|
Additional arguments may be specified after the file name:
|
|
<p>
|
|
<dl>
|
|
<dt><code>crlf</code>
|
|
<dd>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.
|
|
</dl>
|
|
<p>
|
|
<a name="tapedev">
|
|
<dt><em>Emulated tape devices</em>
|
|
<dd>Four types of emulation are supported:
|
|
<dl>
|
|
<p><dt><b>SCSI tapes</b>
|
|
<dd>The argument specifies the tape device name (usually
|
|
<b><i>/dev/st0</i></b>). SCSI tapes are read and written
|
|
using variable length EBCDIC blocks and filemarks exactly
|
|
like a mainframe tape volume.
|
|
<p><dt><b>Optical Media Attach (OMA) virtual files</b>
|
|
<dd>These are read-only files which usually reside on CDROM.
|
|
OMA virtual tapes consist of one CDROM file corresponding
|
|
to each physical file of the emulated tape. An ASCII text
|
|
file called the tape descriptor file (TDF) specifies the
|
|
names of the files which make up the virtual tape.
|
|
The argument specifies the name of the tape descriptor
|
|
file (for example <b><i>/cdrom/tapes/uaa196.tdf</i></b>)
|
|
<p>Each file on the virtual tape can be in one of three
|
|
formats:
|
|
<dl>
|
|
<dt><code>TEXT</code>
|
|
<dd><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.
|
|
<dt><code>FIXED <em>nnnnn</em></code>
|
|
<dd><b><i>FIXED</i></b> files consist of fixed length
|
|
EBCDIC blocks of the specified length
|
|
(<code><em>nnnnn</em></code>)
|
|
<dt><code>HEADERS</code>
|
|
<dd><b><i>HEADERS</i></b> files consist of variable
|
|
length EBCDIC blocks. Each block is preceded by a
|
|
12-byte header.
|
|
</dl>
|
|
<p>If you have any IBM manuals in Bookmanager format on CDROM,
|
|
you can see some examples of TDF files in the
|
|
<b><i>\TAPES</i></b> directory on the CDROM.
|
|
<p><dt><b>AWSTAPE files</b>
|
|
<dd>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 <b><i>ickdsf.ipl</i></b>)
|
|
<p><dt><b>HET files</b>
|
|
<dd>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 <b><i>023178.het</i></b>)
|
|
<p>Additional arguments that allow you to control various HET settings
|
|
are:
|
|
<dl>
|
|
<dt><code>AWSTAPE</code>
|
|
<dd>The <b><i>AWSTAPE</i></b> argument causes HET files to
|
|
be written in AWSTAPE format. This basically, disables
|
|
the additional features provided by the HET format.
|
|
<dt><code>COMPRESS=<em>n</em></code>
|
|
<dt><code>IDRC=<em>n</em></code>
|
|
<dd><b><i>COMPRESS</i></b> and <b><i>IDRC</i></b> control
|
|
whether compression should be used when writing to HET
|
|
files. The value <code><em>n</em></code> can be <b>1</b>
|
|
to turn on compression (the default) or <b>0</b> to turn
|
|
it off. <b><i>IDRC</i></b> is a currently a synonym for
|
|
<b><i>COMPRESS</i></b>, but may be used in the future to
|
|
control other emulated tape drive features.
|
|
<dt><code>METHOD=<em>n</em></code>
|
|
<dd>The <b><i>METHOD</i></b> option allows you to specify
|
|
which compression method to use. You may specify
|
|
<b><i>1</i></b> for ZLIB compression or <b><i>2</i></b>
|
|
for BZIP2 compression. The default is <b><i>1</i></b>.
|
|
<dt><code>LEVEL=<em>n</em></code>
|
|
<dd>The <b><i>LEVEL</i></b> option controls the level of
|
|
compression. It ranges from <b><i>1</i></b> for fastest
|
|
compression to <b><i>9</i></b> for best compression.
|
|
The default is <b><i>4</i></b>.
|
|
<dt><code>CHUNKSIZE=<em>nnnnn</em></code>
|
|
<dd>The <b><i>CHUNKSIZE</i></b> option allows you to create
|
|
HET files that contain different chunk sizes. The AWSTAPE
|
|
(and therefore the HET) format allows each tape block to be
|
|
logically broken up into smaller chunks. For instance, if
|
|
your S/3x0 application creates tapes with a block size of
|
|
27998, those blocks would be broken down into
|
|
<code><em>nnnnn</em></code> sized chunks. To be honest, I
|
|
can't think of a reason you'd want to change this since
|
|
decreasing it may reduce compression performance, but it's
|
|
there if you want it. The range is from <b><i>4096</i></b>
|
|
to <b><i>65535</i></b>. The latter being the default.
|
|
<p />
|
|
</dl>
|
|
<dl>
|
|
The following parameters apply to both AWS and HET emulation files :
|
|
<p />
|
|
<dt><code>MAXSIZE</code>|<code>MAXSIZEK</code>|<code>MAXSIZEM</code>=<em>n</em>
|
|
<dd>Specifies the maximum number of bytes (specified in bytes, Kilobytes or Megabytes) for the emulated file. This parameter defaults to 0, meaning there is no limit on the file size.
|
|
<dt><code>EOTMARGIN</code>=<em>n</em>
|
|
<dd>Specifies the number of bytes remaining before reaching <em>maxsize</em> at which point the tape device will signal the presence of the 'End Of Tape' marker, thus allowing the program to switch to the next tape.
|
|
<p />
|
|
</dl>
|
|
<dl>
|
|
Additionally, if the file name starts with the '@' character (at sign), the file really describes a list of tape emulation files to be loaded in succession.
|
|
<br />The syntax of each line is identical to the information specified that can be specified after the device type when the emulation file is specified directly after the device type in the configuration file.
|
|
<br />If the emulation file filename in the file list is the '*' character, then this specifies a set of options to be applied to all additional emulation files specified in the file list.
|
|
<br />Parameters are appended in succession. In all cases, is the same parameter is specified more than once, the last instance takes precedence.
|
|
<br />
|
|
Therefore, it is possible to specify a set of parameters in the base configuration file, Another set on a '*' line, and another set for each individual lines. Parameter are then appended in that order.
|
|
<p />
|
|
An SCSI tape device should *NOT* be given in a file list.
|
|
</dl>
|
|
<p />
|
|
See the README.TAPE file for additional information, system and application programming for tape devices.
|
|
</dl>
|
|
<p>
|
|
<a name="ctca">
|
|
<dt><em>Channel-to-channel adapters</em>
|
|
<dd>The first argument defines the emulation type, and the remaining
|
|
arguments depend on the emulation type. The following emulation
|
|
types are defined:
|
|
<dl>
|
|
<p><dt><b>CTCI</b> (Channel to Channel link to TCP/IP stack)<p>
|
|
<dd>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 details.<p>
|
|
(Note: The CTCI protocol is only for the Linux version of
|
|
Hercules. For Windows, use the below CTCI protocol instead).
|
|
<p><dt><b>CTCI</b> (Channel to Channel link to Win32 TCP/IP stack)<p>
|
|
<dd>A modified Win32 version of the CTCI protocol for the Windows
|
|
crowd. Note that the protocol name (CTCI) is the same,
|
|
even though the actual implementation is very different. See Fish's
|
|
<a href="http://home.sprintmail.com/~dtrout/Hercules/ctci-w32-index.html">CTCI-W32</a>
|
|
page for further details and information.
|
|
<P><dt><b>CTCT</b> (Channel to Channel Emulation via TCP connection)<p>
|
|
<dd>An emulated CTCA to another Hercules system. Four arguments
|
|
are required:<p>
|
|
<dl>
|
|
<dt><code><em>lport</em></code>
|
|
<dd>specifies the local TCP port. This is the TCP port that
|
|
Hercules will listen on for this CTCA.
|
|
<dt><code><em>rhost</em></code>
|
|
<dd>specifies the remote host. This is the name or IP address
|
|
of the remote system that Hercules is running on, not the
|
|
name or IP address of the OS running on that copy of
|
|
Hercules.
|
|
<dt><code><em>rport</em></code>
|
|
<dd>specifies the remote TCP port. The rport parameter on this
|
|
system must match the lport parameter on the remote system,
|
|
and vice versa.
|
|
<dt><code><em>bufsize</em></code>
|
|
<dd>specifies the buffer size for the link. If this link is used
|
|
for IP traffic, this parameter should be more than the MTU
|
|
of the interface definition in the OS.
|
|
</dl>
|
|
</dl>
|
|
<p>If the first parameter is not one of the recognized CTC emulation
|
|
types, then the driver will operate as in Hercules Version 1, using
|
|
Willem Konynenberg's vmnet package, as described in Axel Schwarzer's
|
|
<a href="http://www.kiyoinc.com/herc3088.html">CTCA 3088</a> document.
|
|
<p>
|
|
<a name="fbadasd">
|
|
<dt><em>FBA DASD devices</em>
|
|
<dd>The argument specifies the name of a file which contains the FBA
|
|
DASD image. The file consists of fixed length 512-byte records,
|
|
each of which represents one physical block of the emulated disk.
|
|
<p>
|
|
To allow access to a minidisk within a full-pack FBA DASD image
|
|
file, two additional arguments may be specified after the file
|
|
name:
|
|
<p>
|
|
<dl>
|
|
<dt><code><em>origin</em></code>
|
|
<dd>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.
|
|
<dt><code><em>numblks</em></code>
|
|
<dd>specifies the number of 512-byte blocks in the minidisk.
|
|
This number must not exceed the number of blocks in the file
|
|
minus the origin.
|
|
If omitted, or if specified as an asterisk, then the minidisk
|
|
continues to the end of the DASD image file.
|
|
</dl>
|
|
<p>
|
|
<a name="ckddasd">
|
|
<dt><em>CKD DASD devices</em>
|
|
<dd>The argument specifies the name of a file containing the disk CKD
|
|
DASD image. The file consists of a 512-byte device header record
|
|
followed by fixed length track images. The length of each track
|
|
image depends on the emulated device type, and is always rounded
|
|
up to the next multiple of 512 bytes.
|
|
<p>
|
|
Volumes larger than 2GB (for example, the 3390 model 3)
|
|
are supported by spreading the data across more than one file.
|
|
Each file contains a whole number of cylinders. The first file
|
|
(which contains cylinders 0-2518 in the case of a 3390) usually
|
|
has _1 as the last two characters of its name. The ckddasd driver
|
|
allocates the remaining files by replacing the last character of
|
|
the file name by the characters 2, 3, etc.
|
|
<p>
|
|
<em>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>
|
|
Alternatively, the argument may specify the name of a file containing
|
|
a compressed CKD DASD image. The CKD driver will automatically detect
|
|
whether the file contains a regular CKD image or a compressed CKD
|
|
image. Refer to the <a href="cckddasd.html">CCKD</a> page for details
|
|
of how to create and use compressed CKD DASD images.
|
|
<a name="comline">
|
|
<dt><em>Communication Adapter</em>
|
|
<dd>
|
|
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.
|
|
<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 line emulates a point-to-point BSC link. There is no point-to-multipoint handling.
|
|
<p />
|
|
The following options define the line emulation behaviour :
|
|
<dl>
|
|
<dt><code>DIAL=IN|OUT|INOUT|NO</code><dd>
|
|
Specifies call direction (if any). If <em>DIAL=NO</em> 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 <em>DIAL=IN|INOUT</em>
|
|
is specified, a TCP incoming call is accepted ONLY if an 'ENABLE' CCW is currently
|
|
executing on the device. If <em>DIAL=OUT</em>, the 'ENABLE' CCW is rejected.
|
|
When <em>DIAL=IN|INOUT</em> 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.
|
|
<dt><code>lhost=hostname|ip address|<em>*</em></code>
|
|
<dd>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 <em>DIAL=OUT</em> is specified has no effect.
|
|
<dt><code>lport=service name|port number</code>
|
|
<dd>Specifies the TCP port for which to listen to incoming TCP calls. This
|
|
value is mandatory for <em>DIAL=IN|INOUT|NO</em>. It is ignored for <em>DIAL=OUT</em>.
|
|
<dt><code>rhost=hostname|ip address</code>
|
|
<dt><code>rport=service name|port number</code>
|
|
<dd>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 <em>DIAL=NO</em>
|
|
is specified. It is ignored for other <em>DIAL</em> values.
|
|
<dt>The following options are tuning options. In most cases, using the default values
|
|
give the best results
|
|
<dt><code>rto=0|-1|nnn|<em>3000</em></code>
|
|
<dd>Specifies the number of miliseconds before terminating a read on a timeout, when
|
|
no read termination control character is received. Specifying 0 means the READ ends
|
|
immediatly. -1 specifies there is no timeout.
|
|
<dt><code>pto=0|-1|nnn|<em>3000</em></code>
|
|
<dd>Specifies the number of miliseconds before terminating a POLL on a timeout, when
|
|
no ACK or NACK sequence is received. Specifying 0 means the POLL ends
|
|
immediatly. -1 specifies there is no timeout.
|
|
<dt><code>eto=0|<em>-1</em>|nnn|<em>10000</em></code>
|
|
<dd>Specifies the number of miliseconds before terminating an ENABLE operation on a timeout.
|
|
the timeout applies when <em>DIAL=NO|IN|INOUT</em> is specified, the outgoing TCP call fails (<em>DIAL=NO</em>)
|
|
and there is no previously or currently established TCP connection for this line. When <em>DIAL=NO</em> is
|
|
specified, the timeout defaults to 10 seconds. for <em>DIAL=IN|INOUT</em>, the timeout
|
|
defaults to -1.
|
|
</dl>
|
|
<dd>
|
|
|
|
</dl>
|
|
<p>
|
|
A comment preceded by a pound sign may be appended to any device
|
|
definition statement.
|
|
<p><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="hercinst.html"><img src="gifs/back.gif" border=0 alt="back"></a>
|
|
</center>
|
|
<small>
|
|
<p>Last updated 6 June 2003
|
|
</BODY>
|
|
</HTML>
|