This page describes the configuration file for the Hercules S/370, ESA/390, and z/Architecture emulator.
The configuration file hercules.cnf contains the processor and device layout. It is roughly equivalent to the IOCDS on a real System/390. The configuration file is an ASCII text file.
Please note that the below example configuration file should not be considered a good example of what an actual configuration file looks like. It is only meant to illustrate what some of the supported configuration file statements look like and how they are used.
|
Blank lines, and lines beginning with a # sign or an asterisk, are treated as comments.
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:
ARCHMODE S/370 | ESA/390 | z/Arch | ESAME
specifies the initial architecture mode:
S/370 for OS/360, VM/370, and MVS 3.8.
ESA/390 for MVS/XA, MVS/ESA, OS/390, VM/ESA, VSE/ESA,
Linux/390, and ZZSA.
z/Arch or ESAME for z/OS and zLinux.
ESAME is a synonym for z/Arch.
When z/Arch or ESAME is specified,
the machine will always IPL in ESA/390 mode,
but is capable of being switched into z/Architecture mode after IPL.
This is handled automatically by all z/Architecture operating systems.
ASN_AND_LX_REUSE DISABLE | ENABLE
specifies that the ASN-and-LX-Reuse Facility (ALRF) is to be disabled
or enabled. The default is disabled. This is a z/Architecture-only
feature (it is always disabled for S/390 or ESA/390). Set this
to ENABLE if the operating system supports
this z/Architecture feature and the use of this feature is desired.
Set it to DISABLE or do not specify anything
if the operating system doesn't support this feature, and it
inadvertently sets CR0 bit 44 to 1, usually leading to unexpected
program interrupt when instructions such as LASP are issued.
ASN_AND_LX_REUSE may be abbreviated as ALRF
AUTO_SCSI_MOUNT NO | YES | nn
specifies whether automatic detection of SCSI tape mounts are to be enabled or not.
Specifying NO or 0 seconds (the default) indicates
the option is disabled, forcing all SCSI tape mounts to be done
manually via an appropriate devinit command.
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 YES
is the same as specifying 5 seconds, the current default interval.
The scsimount panel command may also be used to display
and/or modify this value on demand once Hercules has been started. Note
too that the scsimount panel command also lists any mounts
and/or dismounts that may still be pending 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).
Note: 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.
CODEPAGE codepage
specifies the codepage conversion table used for ASCII/EBCDIC translation.
"default" specifies traditional Hercules codepage. Code pages "437/037", "437/500" and "850/273" are also supported.
Iconv single byte codepages may also be used (e.g. "UTF8/EBCDIC-CP-NL").
If no codepage is specified then the environment variable HERCULES_CP will be inspected. The default codepage used is "default"
CNSLPORT nnnn
specifies the port number (in decimal) to which tn3270 and telnet clients will connect.
The CNSLPORT statement may also have the form of host:port, where the telnet console server will bind to the specified address.
CONKPALV (idle,intv,count)
specifies the tn3270 console and telnet clients keep-alive option values that control automatic detection of disconnected tn3270/telnet client sessions.
idle specifies the number of seconds
of inactivity until the first keep-alive probe is
sent (idle time until first probe, or probe frequency).
intv
specifies the interval in seconds between when successive
keep-alive packets are sent if no acknowledgement is received from
the previous one (i.e. the timeout value of the probes themselves).
count specifies the number of unacknowledged
keep-alive packets sent before the connection is considered to have
failed.
The default values are 3, 1, and 10. That is, send the initial probe 3 seconds after the line goes idle and then wait no more than one second for it to be responded to. Do this 10 times before considering the client as having died.
Note: This is a built-in feature of TCP/IP and allows detection of unresponsive TCP/IP connections and not idle clients. That is to say, your connection will not be terminated after 3 seconds of idle time. Your 3270 session can remain idle for many minutes without any data being transmitted. If the TCP/IP stack at the other end of the connection -- not your 3270 client itself -- fails to respond to the internal keep-alive probe packets, then it means that the TCP/IP stack is down or there has been a break in the connection. Thus, even if your 3270 client is completely idle, your system's TCP/IP stack itself should still respond to the keep-alive 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.
The three values can also be modified on-demand via the conkpalv
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.
Note:
On Windows platforms the count value is ignored and
cannot be changed from its default value of 10.
Also, some older platforms may ignore all of the values specified
and use platform default values instead.
CPUMODEL xxxx
specifies the 4 hexadecimal digit CPU model number stored by the STIDP instruction
CPUPRIO nn
specifies the priority of the CPU thread. Default is a nice value of 15, which means a low priority such that I/O can be scheduled and completed in favour of CPU cycles being burned. On Multi-CPU systems, a real CPU can be "dedicated" to Hercules, by giving the CPU thread a very high dispatching priority (-20). See "Thread Priorities" below for more information.
Caution: CPUPRIO should not have a higher dispatching priority than the TOD Clock and timer thread.
CPUSERIAL xxxxxx
specifies the 6 hexadecimal digit CPU serial number stored by the STIDP instruction
CPUVERID xx
specifies the 2 hexadecimal digit CPU version code stored by the STIDP instruction. The default version code is FD when ARCHMODE S/370 or ARCHMODE ESA/390 is specified. For the z/Architecture mode, 00 is used as default.
DEFSYM symbol value
Defines symbol symbol as to contain value value. The symbol can then be the object of a substitution later in the configuration file or for panel commands. If value contains blanks or spaces, then it should be enclosed in double quotation marks ("). See substitutions for a more in-depth discussion on this feature.
Substitution is available even in configuration statements,
meaning it is possible to perform substitution in the DEFSYM statement itself.
However, symbols are always defined as the last step in the process, so attempting
to self define a symbol will result in an empty string:
DEFSYM FOO $(FOO)
DEVPRIO nn
specifies the priority of the device threads. The default value is 8. See "Thread Priorities" below for more information.
Caution: DEVPRIO should not have a higher dispatching priority than the TOD Clock and timer thread.
DEVTMAX -1 | 0 | nnn
specifies the maximum number of device threads allowed.
Specify -1 to cause 'one time only' temporary threads to be
created to service each I/O request to a device. Once the I/O request is
complete, the thread exits. Subsequent I/O to the same device will cause
another worker thread to be created again.
Specify 0 to cause an unlimited number of 'semi-permanent'
threads to be created on an 'as-needed' basis. With this option, a thread
is created to service an I/O request for a device if one doesn't already
exist, but once the I/O is complete, the thread enters an idle state waiting
for new work. If a new I/O request for the device arrives before the timeout
period expires, the existing thread will be reused. The timeout value is
currently hard coded at 5 minutes. Note that this option can cause one thread
(or possibly more) to be created for each device defined in your
configuration. Specifying 0 means there is no limit to the
number of threads that can be created.
Specify a value from 1 to nnn to set an upper limit
to the number of threads that can be created to service any I/O request to
any device. Like the 0 option, each thread, once done servicing
an I/O request, enters an idle state. If a new request arrives before the
timeout period expires, the thread is reused. If all threads are busy when
a new I/O request arrives however, a new thread is created only if the
specified maximum has not yet been reached. If the specified maximum number
of threads has already been reached, then the I/O request is placed in a queue
and will be serviced by the first available thread (i.e. by whichever thread
becomes idle first). This option was created to address a threading issue
(possibly related to the cygwin Pthreads implementation) on Windows systems.
The default for Windows is 8. The default for all other systems
is 0.
DIAG8CMD DISABLE | ENABLE
When set to ENABLE, commands issued through diagnose 8 will be
executed by hercules as hercules commands. When set to DISABLE,
commands issued through the diagnose 8 interface will be ignored.
The default is DISABLE
Caution: Enabling this feature may have security consequences
Note that when this feature is enabled systems
running under hercules can even issue host commands through the Hercules
sh (shell) command. This ability may be disabled via the
SHCMDOPT statement.
ECPSVM YES | NO | LEVEL nn
specifies whether ECPS:VM (Extended Control Program Support : Virtual Machine)
support is to be enabled. If YES is specified, then the support
level reported to the operating system is 20. The purpose of
ECPS:VM is to provide to the VM/370 Operating system a set of shortcut
facilities to perform hypervisor functions (CP Assists) and virtual
machine simulation (VM Assists). Although this feature does not affect
VM Operating system products operating in XA, ESA or z/Architecture mode,
it will affect VM/370 and VM/SP products running under VM/XA, VM/ESA or z/VM.
Running VM/370 and VM/SP products under VM/XA, VM/ESA or z/VM should be
done with ECPS:VM disabled. ECPS:VM should not be enabled in an AP or MP
environment. ECPS:VM has no effect on non-VM operating systems. It is
however recommended to disable ECPS:VM when running native non-VM operating
systems. If a specific LEVEL is specified, this value will be reported
to the operating system when it issues a Store ECPS:VM level, but it
doesn't otherwise alter the ECPS:VM facility operations. This is a partial
implementation.
HERCPRIO nn
specifies the process priority for Hercules. The default is 0. See "Process Priorities" below for more information.
HTTPPORT nnnn [AUTH | NOAUTH] [ userid password ]
specifies the port number (in decimal) on which the HTTP server
will listen. The port number must either be 80
or within the range 1024 - 65535 inclusive. If no HTTPPORT statement is
present or an invalid port number is specified, then the HTTP server thread
will not be activated.
AUTH indictates that a userid and password are required to access
the HTTP server, whereas NOAUTH indicates that a userid and password
are not required. The userid and password may be any valid string.
HTTPROOT directory
specifies the root directory where the HTTP server's files reside. If not specified, the default value for Win32 builds of Hercules is the directory where the Hercules executable itself is executing out of, and for non-Win32 builds it is the directory specified as the default package installation directory when the Hercules executable was built (which can vary depending on how the Hercules package was built, but is usually /usr/local/share/hercules/).
Note: Windows users of Hercules who do not have the complete Cygwin package installed (i.e. only have the required Cygwin DLLs installed instead) should specify this value in the form: "/cygdrive/x/pathname/" where 'x' is the Windows drive letter. For example, if the Windows directory where the http server's files reside is "K:\Hercules\html\", then you should specify "/cygdrive/k/Hercules/html/" on your HTTPROOT statement.
IGNORE INCLUDE_ERRORS
Indicates that errors caused by subsequent
INCLUDE statements
for files which do not exist should instead be ignored rather
than causing startup to be aborted (as would otherwise normally
occur).
INCLUDE filepath
An INCLUDE statement tells Hercules configuration file
processing to treat the contents of the file specified by filepath
as if its contents had appeared in the configuration file at the point
where the INCLUDE statement appears.
Note that the included file may itself contain yet another
INCLUDE statement as long as the maximum nesting depth
(current 8) is not exceeded.
IODELAY usec [NOWARN]
specifies the amount of time (in microseconds) to wait after
an I/O interrupt is ready to be set pending. This value can also be
set using the Hercules console. The purpose of this parameter is to
bypass a bug in the Linux/390 and zLinux dasd.c
device driver. The problem is more apt to happen under Hercules than
on a real machine because we may present an I/O interrupt sooner than a
real machine.
If the IODELAY value is non-zero a warning message (HHCCF037W) will be
issued unless NOWARN is specified.
NOTE : OSTAILOR LINUX no longer sets
IODELAY to 800 since the problem described above is no longer present in
recent versions of the Linux kernel.
LDMOD module list
specifies additional modules that are to be loaded by the hercules dynamic loader. The default search order is with the hercules directory in the default DLL search path. Most systems also support absolute filenames (ie names starting with '/' or '.') in which case the default search path is not taken.
Multiple LDMOD statements may be used.
LOADPARM xxxxxxxx
specifies the eight-character IPL parameter which is used by some operating systems to select system parameters.
LOGOPT [TIMESTAMP | NOTIMESTAMP]
sets Hercules log options. TIMESTAMP causes messages to the log to be time stamped. NOTIMESTAMP prevents time stamping of log messages. TIMESTAMP and NOTIMESTAMP may be abbreviated as TIME and NOTIME respectively.
The default is TIMESTAMP.
LPARNAME name
specifies the LPAR name returned by DIAG X'204'. The default is
HERCULES.
MODEL name
specifies the MODEL name returned by the STSI instruction. The default is
EMULATOR.
PLANT name
specifies the PLANT name returned by the STSI instruction. The default is
ZZ.
MANUFACTURER name
specifies the MANUFACTURER name returned the STSI instruction. The default is
HRC.
MAINSIZE nnnn
specifies the main storage size in megabytes, where
nnnn is a decimal number. The lower limit is 2.
The actual upper limit is determined by your host system's architecture
and operating system, and (on some systems) the amount of physical
memory and paging space you have available.
MODPATH path
specifies the path where dynamic modules are loaded from. When a modpath statement is specified, the path on the modpath statement is searched before the default path is searched. When a relative path is specified is interpreted as a relative path within the default search path, if an absolute path is specified is interpreted as such.
The default MODPATH is hercules, which means modules are loaded from the directory hercules within the default LD_LIBRARY_PATH.
MOUNTED_TAPE_REINIT DISALLOW | ALLOW
specifies whether reinitialization of tape drive devices (via the
devinit command, in order to mount a new tape) should
be allowed if there is already a tape mounted on the drive.
Specifying ALLOW (the default) indicates new tapes may
be mounted (via 'devinit nnnn new-tape-filename')
irrespective of whether or not there is already a tape mounted on the drive.
Specifying DISALLOW prevents new tapes from being mounted
if one is already mounted. When DISALLOW is specified
and a tape is already mounted on the drive, it must first be unmounted
(via the command 'devinit nnnn *') before
the new tape can be mounted. Otherwise the devinit attempt to mount
the new tape is rejected.
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.
Also note that for SCSI tape drives the 'devinit nnnn *'
command has no affect 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).
NUMCPU nn
specifies the number of emulated CPUs.
Note:
Multiprocessor emulation is only available when the definition of
the compile-time variable MAX_CPU_ENGINES
in the file config.h has a value of more than 1.
Current versions of Hercules already have this value
set to 2 by default, so all you need to do is specify
NUMCPU 2
in your configuration file. If you wish to define a greater value
for MAX_CPU_ENGINES, use the
--enable-multi-cpu=NUMBER
option when you do your ./configure before doing your
make.
Multiprocessor emulation works best if your host system actually has more than one physical CPU, but you can still emulate multiple CPUs nervertheless even on a uniprocessor system (and you might even achieve a small performance benefit when you do). There is little point, however, in specifying NUMCPU greater than 1 unless your guest operating system (running under Hercules) is actually able to support multiple CPUs (and if you do not actually need multiprocessor emulation, then setting MAX_CPU_ENGINES to 1 at compile time might even produce a slight performance advantage too).
NUMVEC nn
specifies the number of emulated vector facilities. Default is one per CPU. Only available by default in ESA/390 mode.
OSTAILOR OS/390 | z/OS |
VM | VSE | LINUX | QUIET | NULL
specifies the intended operating system. The effect of this
parameter is to reduce control panel message traffic by
selectively suppressing trace messages for program checks
which are considered normal in the specified environment.
QUIET discards all exception messages.
NULL allows all exception messages to be logged.
Optionally prefix any value except QUIET or
NULL 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).
If the OSTAILOR
statement is omitted, exception messages for program checks
10, 11, 16, and 1C are suppressed.
Use the ostailor or pgmtrace panel
commands to display or alter the current settings.
PANRATE SLOW | FAST | nn
specifies the panel refresh rate, in milliseconds between refreshes. SLOW is the same as 500, and FAST is the same as 50. A value less than the Linux system clock tick interval (10 on Intel, 1 on Alpha), or more than 5000, will be rejected. SLOW is the default.
PANTITLE "title-string"
specifies an optional console window title-bar string to be used in place of the default one supplied by Windows. If the value contains any blanks it must be enclosed within double-quotes.
This option allows one to distinguish between different Hercules sessions when running more than one instance of Hercules on the same Windows host.
Note that this option has no effect when Hercules is run under control of the Hercules GUI since Hercules's console window is hidden in favor of using the GUI's console window instead.
PGMPRDOS RESTRICTED | LICENSED
specifies whether or not Hercules will run licensed program product ESA
or z/Architecture operating systems. Specify RESTRICTED to
make Hercules emulate an IFL (Integrated Facility for Linux) CPU. With
this specified, licensed ESA or z/Architecture OSes will refuse to
start. OS/390 and z/OS will enter an A7A wait state, with reason code 7,
at IPL time. Specify LICENSED to allow these operating
systems to run normally. This parameter has no effect on Linux/390,
Linux for z/Series, or any 370-mode OS.
NOTE: It is YOUR responsibility to comply with the terms of the license for the operating system you intend to run on Hercules. If you specify LICENSED and run a licensed operating system in violation of that license, then don't come after the Hercules developers when the vendor sends his lawyers after you.
RESTRICTED is the default. Specifying
LICENSED will produce a message at Hercules startup to
remind you of your responsibility to comply with software license terms.
SHCMDOPT DISABLE | NODIAG8
When set to DISABLE, sh (shell) commands are globally disabled, and will result
in an error if entered either directly via the Hercules hardware console or
programmatically via the DIAG8CMD interface.
When set to NODIAG8 only the programmatic execution of shell commands via the
the diagnose 8 interface is disabled, but sh (shell) commands entered directly
via the Hercules hardware console will still work.
NOTE: "entered directly via the Hercules hardware console" also pertains to both commands entered via the HTTP server facility as well as commands entered via .rc "run command" scripts.
SHRDPORT nnnn
specifies the port number (in decimal) on which the Shared Device server
will listen. Specifying SHRDPORT will allow other Hercules instances
to access devices on this instance. (Currently only DASD devices may
be shared). By default, the other Hercules instances (clients) will
use port 3990. If you specify a different port number, then you will
have to specify this port number on the device statement for the other
Hercules clients.
If no SHRDPORT statement is present then the Shared Device server thread
will not be activated.
SYSEPOCH yyyy [±years]
specifies the base date for the TOD clock. Use the default value
(1900) for all systems except OS/360. Use 1960
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
1900 or 1960 will be accepted. Other values
will produce a warning message with the equivalent values to specify in
the SYSEPOCH statement.
An optional year offset may be specified, and will be treated as though
it had been specified on a YROFFSET
statement.
TIMERINT DEFAULT | nnnn
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. The default interval is 50 microseconds, which strikes a reasonable balance between clock accuracy and overall host performance. The minimum allowed value is 1 microsecond and the maximum is 1000000 microseconds (i.e. one second).
Caution: While a lower TIMERINT value may help increase the accuracy of your guest's TOD Clock and CPU Timer values, it could also have a severe negative impact on the overall performance of your host operating system. This is especially true when a low TIMERINT value is coupled with a high HERCPRIO and TODPRIO priority setting. Exercise extreme caution when choosing your desired TIMERINT in relationship to your chosen HERCPRIO and TODPRIO priority settings.
TODDRAG nn
specifies the TOD clock drag factor. This parameter can be used to slow down or speed up the TOD clock by a factor of nn. A significant slowdown can improve the performance of some operating systems which consume significant amounts of CPU time processing timer interrupts. A drag factor of 2.0 slows down the clock by 50%. A drag factor of 0.5 doubles the speed of the clock. A drag factor of 1.01 slows down the clock by 1%, and 0.99 speeds up the clock by 1%.
TODPRIO nn
specifies the priority of the TOD Clock and timer thread. The default value is -20. See "Thread Priorities" below for more information.
Caution: TODPRIO should be given a dispatching priority equal to or higher than any other thread within Hercules.
TZOFFSET ±hhmm
specifies the hours and minutes by which the TOD clock will
be offset from the current system time. For GMT, use the
default value (0000). For timezones west of Greenwich, specify
a negative value (example: -0500 for US Eastern Standard
Time, -0800 for US Pacific Standard Time).
For timezones east of Greenwich, specify a positive value
(example: +0100 for Central European Time,
+0930 for South Australian Time).
XPNDSIZE nnnn
specifies the expanded storage size in megabytes, where
nnnn is a decimal number. The lower limit is 0.
The actual upper limit is determined by your host system's architecture
and operating system, and (on some systems) the amount of physical
memory and paging space you have available.
YROFFSET ±years
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 YROFFSET -28, 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 SYSEPOCH
or more than 142 years later than that value will produce unexpected
results.
A comment preceded by a # sign may be appended to any system parameter statement.
In configuration and device statements, as well as in panel commands, symbols may be substituted for text.
To substitute symbol symbol with its contents, the symbol should be enclosed within parenthesis and preceded by a $ sign. For example, if symbol FOO contains the text string "BAR" then $(FOO) will be substituted with the string "BAR";. Symbol names are case sensitive.
DEFSYM TAPEDIR "/home/hercules/tapes"
...
0380 3420 $(TAPEDIR)/scratch.aws
...In this example, device 0380 will be a 3420 loaded with the AWS tape file in /home/hercules/tapes/scratch.aws
When multiple devices are defined with a single device definition record, then the symbols
- CUU
(3 digits device number, upper case hexadecimal digits) - CCUU
(4 digits device number, upper case hexadecimal digits) - cuu
(3 digits device number, lower case hexadecimal digits) - ccuu
(4 digits device number, lower case hexadecimal digits)
are defined to contain for each device the relevant device address. For example:
0200,0201 3340 /home/hercules/dasds/myvols.$(CUU)
will define two 3340 packs, with device 0200 being loaded with the file myvols.200 and device 0201 defined with myvols.201.
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.
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.
To be able to specify the '$(' string without incurring substitution, an additional '$' sign should be used. For example, $$(FOO) will not be substituted. If substitution is required but the preceding text is to contain a '$' sign as the very last character, then $$$(FOO) should be specified. Thus, if symbol FOO contains "BAR", then $$(FOO) will remain "$$(FOO)" while $$$(FOO) will become "$BAR".
Substitution is not recursive (only one substitution pass is made).
Enhanced symbol substitution differs from the above normal symbol substitution in several very important ways:
First, the syntax is different. Enhanced substitution symbol names are specified
using ${var} (dollar + brace) rather than $(var)
(dollar + parenthesis).
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 '=' or a
colon-equal-sign ':='.
For example, specifying "${DASD_PATH=dasd/}" 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 "dasd/"
instead. If no default value is specified then an empty string is used instead.
Finally, enhanced symbol substitution occurs only from host defined environment
variables and not from any identically named DEFSYM symbol
should one exist. For example, if environment variable 'FOO' is defined with the
value "bar", then the configuration file statement "DEFSYM FOO myfoo"
followed immediately by the statement "${FOO}" causes the value
"bar" to be substituted and not 'myfoo' as might
otherwise be believed, whereas the statement "$(FOO)", since it is
a normal symbol substitution sequence does get replaced with "myfoo"
(since that was the value defined to it via the preceding DEFSYM
statement).
In other words each symbol substitution technique is supported completely separately
from one another. DEFSYM 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.
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 "${FOO}", "${foo}",
"${Foo}", etc, all cause the same value to be substituted on Windows,
whereas the DEFSYM symbols $(FOO) and $(foo),
being two completely different and unique symbols, could be substituted with two
completely different values (since DEFSYM is
case sensitive across all supported platforms, including Windows).
To substitute symbol symbol 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 FOO holds the value "BAR", then
${FOO} will be substituted with the string "BAR". If the environment variable
"FOO" is not defined then a null (empty) string is substituted instead.
If the string "${FOO:=myfoo}" 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 "myfoo" instead if the environment variable
FOO is currently undefined.
Note too that the default value is a literal
string and no substitution is applied to it. Thus attempting to use the syntax
"${foo=${bar}}" will not yield the expected results. It will
not be substituted with the currently defined value of the "bar" environment
variable, but rather will always be substituted with the literal string
"${bar" followed immediately by the literal character '}'.
Symbol names (environment variable names) are not case sensitive on Windows whereas they might be on other host operating systems.
Note: Under Linux, a process is a thread and thread priority information applies instead.
For Windows, the following conversions are used for translating Unix process priorities to Windows process priority classes:
| Unix Priority |
Windows Process Priority Class |
Meaning |
|
|---|---|---|---|
| -20 to -16 | Real-time | 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. | |
| -15 to -9 | High | 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. | |
| -8 to -1 | Above Normal | Process that has priority above the Normal class but below the High class. | |
| 0 to 7 | Normal | Process with no special scheduling needs. | |
| 8 to 14 | Below Normal | Process that has priority above the Idle class but below the Normal class. | |
| 15 to 20 | Idle | 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. |
Caution: On Windows, the value you choose for your Process Priority has a direct impact on how your Thread Priorities are interpreted! You should never modify one without understanding what impact your doing so might have on the other!
On a Linux/Unix host, Hercules needs to be a setuid root
program to allow it to reset its dispatching priority to a high
(negative) value
(i.e., chown root.root hercules; chmod +s hercules).
For Windows, the following conversions are used for translating Linux/Unix thread priorities to Windows thread priorities:
| Unix Priority |
Windows Thread Priority |
Meaning |
|
|---|---|---|---|
| -20 to -16 | Time Critical | Base priority of 15 for Idle, Below Normal, Normal, Above Normal, or High class processes, and a base priority of 31 for Realtime class processes. | |
| -15 to -9 | Highest | Priority 2 points above the priority class. | |
| -8 to -1 | Above Normal | Priority 1 point above the priority class. | |
| 0 to 7 | Normal | Normal priority for the priority class. | |
| 8 to 14 | Below Normal | Priority 1 point below the priority class. | |
| 15 to 19 | Lowest | Priority 2 points below the priority class. | |
| 20 | Idle | Base priority of 1 for Idle, Below Normal, Normal, Above Normal, or High class processes, and a base priority of 16 for Realtime class processes. |
Caution: On Windows, your Thread Priority is interpreted differently based on your chosen Process Priority setting! You should never modify your Thread Priority settings without first reviewing your chosen Process Priority setting!
The remaining statements in the configuration file are device records. There must be one device record for each I/O device or group of identical I/O devices. The format of the device record is:
devnum(s) devtype [ arguments ]
where the generic syntax for device numbers is
[n:]CCUU[,CCUU][-CCUU][.nn][...]
as explained below:
devnum(s)is either a single devnum, a range of devnums (separated by a '-' (dash)), a count of devnums (separated by a '.' (dot/period/stop)), or a comma separated list of devnums. Examples would be 200-210 or 0300.10 or 0400,0403 or 0100,0110-011F.
All devices defined when devnums specifies more than one device have identical characteristics (except for the device number itself). All devices defined as a group must be defined on a single channel. A channel is defined as a contiguous group of 256 (or hexadecimal 100) devices. 0010 and 0020 are on the same channels. 0100 and 0210 are not.
See devnum immediately below for an explanation of how each device number is specified.
The 4 special subtitution symbols CUU, CCUU, cuu and ccuu are also defined for each device in a device group. See substitutions for details.
devnumis 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.
Channel Set / Logical Channel SubsystemAn 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 :
1:0400-040F 3270
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.
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.
Not all S/390 or z/Architecture operating systems support Multiple Logical Channel Subsystems (this feature was introduced with the z9-109).
If no Channel Set or Logical Channel Subsystem Identification is specified, then it is assumed to be 0.
devtypeis the device type. Valid device types are shown in the table below.
argumentsis a list of parameters whose meaning depends on the device type. The arguments required for each class of device are shown below.
Thread Priorities
On a Linux/Unix host, Hercules needs to be a setuid root
program to allow it to reset its dispatching priority to a high
(negative) value
(i.e., For Windows, the following conversions are used for translating Linux/Unix thread priorities to Windows thread priorities:
Device definitionsThe 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:
where the generic syntax for device numbers is
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||