Snipix Technologies

Hercules Configuration File

This page describes the configuration file for the Hercules S/370 and ESA/390 emulator.

The configuration file hercules.cnf contains the processor and device layout. It is roughly equivalent to the IOCDS on a real System/390. The configuration file is an ASCII text file.

Example configuration file

#
# System parameters
#

CPUSERIAL 000611
CPUMODEL  3090
MAINSIZE  64
XPNDSIZE  0
CNSLPORT  3270
NUMCPU    1
LOADPARM  0120....
SYSEPOCH  1900
TZOFFSET  -0500

#
# 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
0580    3420    ickdsf.ipl
0581    3420    /dev/st0
0582    3420    /cdrom/tapes/uaa196.tdf

Comment lines

Blank lines, and lines beginning with a hash sign or an asterisk, are treated as comments.

System parameters

System parameters may appear in any order but they must precede all device records. Each system parameter must be on a separate line. The following system parameters may be specified:

CPUID xxxxxx
specifies the 6 hexadecimal digit CPU serial number stored by the STIDP instruction
CPUMODEL xxxx
specifies the 4 hexadecimal digit CPU model number stored by the STIDP instruction
MAINSIZE nnnn
specifies the main storage size in megabytes, where nnnn is a decimal number in the range is 2 to 2048
XPNDSIZE nnnn
specifies the expanded storage size in megabytes, where nnnn is a decimal number in the range is 0 to 2048
CNSLPORT nnnn
specifies the port number (in decimal) to which tn3270 and telnet clients will connect
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 hercules.h 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.
LOADPARM xxxxxxxx
specifies the eight-character IPL parameter which is used by some operating systems to select system parameters
SYSEPOCH yyyy
specifies the base date for the TOD clock. Use the default value (1900) for all systems except OS/360. OS/360 expects the base date to be 1960, but specifying this value causes an error because OS/360 regards 2000 as an invalid date. For OS/360, SYSEPOCH 1988 is recommended. This makes the year 2000 appear to be 1972.
TZOFFSET ±hhmm
specifies the hours and minutes by which the TOD clock will be offset from the current system time. For GMT, use the default value (0000). For timezones west of Greenwich, specify a negative value (example: -0500 for Eastern Standard Time, -0800 for Pacific Standard Time). For timezones east of Greenwich, specify a positive value (example: +0100 for Central European Time, +0930 for South Australian Time).
TODDRAG nn
specifies the TOD clock drag factor. This parameter can be used to slow down the TOD clock by a factor of nn, which can improve the performance of some operating systems which consume significant amounts of CPU time processing timer interrupts.
OSTAILOR OS/390 | VM | LINUX
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.

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

Device records

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

devnum devtype [arguments]

where:

devnum
is a 1 to 4 digit hexadecimal number (for ESA/390), or a 1 to 3 digit hexadecimal number (for S/370). The device number uniquely identifies each device to the operating system.
devtype
is the device type. Valid device types are:
Device type Description Emulated by
3270 Local non-SNA 3270 TN3270 client connection
1052, 3215 Console printer-keyboards Telnet client connection
1442, 2501, 3505 Card readers Disk file (ASCII or EBCDIC)
3525 Card punch Disk file (ASCII or EBCDIC)
1403, 3211 Line printers Disk file (ASCII)
3420, 3480 Tape drives Disk file, CDROM, or SCSI tape
3310, 3370, 9336
0671		 FBA direct access storage devices Disk file
2311, 2314, 3330
3350, 3380, 3390		 CKD direct access storage devices Disk file
arguments
is a list of parameters whose meaning depends on the device type. The arguments required for each class of device are shown below.

Arguments required for each device type

Local non-SNA 3270 devices
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 CPU record. 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.

Console printer-keyboard devices
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 CPU record. 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.

Card reader devices
The argument specifies the name of a file containing card images. Additional arguments may be specified after the file name:

ebcdic
specifies that the file contains fixed length 80-byte EBCDIC records with no line-end delimiters.
ascii
specifies that the file contains variable length lines of ASCII characters delimited by line feeds or carriage return line feed sequences at the end of each line.
trunc
specifies, for ASCII files, that lines longer than 80 characters are truncated instead of producing a unit check error.
eof
specifies that unit exception status is presented after reading the last card in the file. If eof is not specified, then end of file results in unit check status with intervention required in the sense bytes.

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.

Card punch devices
The argument specifies the name of a file to which the punched output will be written. Additional arguments may be specified after the file name:

ascii
specifies that the file will be written as variable length lines of ASCII characters delimited by line feeds or carriage return line feed sequences at the end of each line. Trailing blanks are removed from each line. If the ascii argument is not specified, the file is written as fixed length 80-byte EBCDIC records with no line-end delimiters.
crlf
specifies, for ASCII files, that carriage return line feed sequences are written at the end of each line. If the crlf argument is not specified, then line-feeds only are written at the end of each line.

Line printer devices
The argument specifies the name of a file to which the printer output will be written. The output is written in the form of variable length lines of ASCII characters delimited by line feeds or by carriage return line feed sequences. Trailing blanks are removed from each line. Carriage control characters are translated to blank lines or ASCII form feed characters. If the file exists it will be overwritten. Additional arguments may be specified after the file name:

crlf
specifies, for ASCII files, that carriage return line feed sequences are written at the end of each line. If the crlf argument is not specified, then line-feeds only are written at the end of each line.

Emulated tape devices
Three type of emulation are supported:

SCSI tapes
The argument specifies the tape device name (usually /dev/st0). SCSI tapes are read and written using variable length EBCDIC blocks and filemarks exactly like a mainframe tape volume.

Optical Media Attach (OMA) virtual files
These are read-only files which usually reside on CDROM. OMA virtual tapes consist of one CDROM file corresponding to each physical file of the emulated tape. An ASCII text file called the tape descriptor file (TDF) specifies the names of the files which make up the virtual tape. The argument specifies the name of the tape descriptor file (for example /cdrom/tapes/uaa196.tdf)

Each file on the virtual tape can be in one of three formats:

TEXT
TEXT files consist of variable length ASCII records delimited by carriage return line feed sequences at the end of each record. Each record is translated to EBCDIC and presented to the program as one physical tape block.
FIXED nnnnn
FIXED files consist of fixed length EBCDIC blocks of the specified length (nnnnn)
HEADERS
HEADERS files consist of variable length EBCDIC blocks. Each block is preceded by a 12-byte header.

If you have any IBM manuals in Bookmanager format on CDROM, you can see some examples of TDF files in the \TAPES directory on the CDROM.

AWSTAPE files
These contain a complete tape in one file. AWSTAPE files consist of variable length EBCDIC blocks. Each block is preceded by a 6-byte header. Filemarks are represented by a 6-byte header with no data. This is the same format as is used by the P/390. The argument specifies the location of the AWSTAPE file (for example ickdsf.ipl)

FBA DASD devices
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.

To allow access to a minidisk within a full-pack FBA DASD image file, two additional arguments may be specified after the file name:

origin
specifies the relative block number within the DASD image file at which the minidisk begins. The number must be less than the number of blocks in the file. The default origin is zero.
numblks
specifies the number of 512-byte blocks in the minidisk. This number must not exceed the number of blocks in the file minus the origin. If omitted, or if specified as an asterisk, then the minidisk continues to the end of the DASD image file.

CKD DASD devices
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.

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) is the file named in the configuration statement. The ckddasd driver allocates the remaining files by replacing the last character of the file name by the characters 2, 3, etc.

A comment preceded by a hash sign may be appended to any device definition statement.

If you have a question about Hercules, see the Hercules Frequently-Asked Questions page.

Last updated 21 May 2000