Installing HercGUI involves the following steps:
- Installing the prerequisite Microsoft Visual C++ 2005 Service Pack 1 Redistributable Package ATL Security Update,
or: Microsoft Visual C++ 2008 Service Pack 1 Redistributable Package ATL Security Update. - Installing the prerequisite FishLib support library DLL
- Installing HercGUI itself
Note: There are separate download links for each supported platform architecture, 32-bit and 64-bit. Be sure to install the appropriate version(s) for your particular platform.
Note 2: if you are running any 64-bit version of Windows (e.g. Windows XP Professional x64 Edition, Windows Server 2003 x64, etc) then you will need to install both the 32-bit and the 64-bit versions! This is because the x64 version of Windows allows you to also run 32-bit programs, and some of the programs are 32-bit programs, thus requiring the 32-bit version of the redistributables in addition to the normal 64-bit version needed by x64 Windows.
FishLib is installed by simply unzipping the distribution into a directory of your own choosing and then adding that directory to your Windows PATH variable (so that Windows can find it whenever you try running HercGUI). Alternatively, you can place the FishLib DLL into the same directory as the HercGUI executable, but this is not recommended since it makes it harder to update FishLib if you have separate copies of it in several different directories. It's better to keep it in one directory and simply add that directory to your Windows PATH.
Installing HercGUI itself is easy: simply unzip the distribution binaries into a directory of your own choosing and then double-click on the icon to start it. The first time you run it you will need to configure your Preferred directories so it can know where the load the Hercules emulator from. (See the "Preferences" section further below)
Uninstalling is pretty much the reverse: just delete everything. Note however that HercGUI does add a new key to your Windows registry to hold some configuration settings, so if you really want to completely rid yourself of HercGUI, you'll also have to manually delete the
HKEY_CURRENT_USERS/Software/Software Development Laboratories/Hercules
branch from the registry using the 'regedit' utility that comes with Windows. (If you don't know what 'regedit' is or how to use it, then I suggest you just leave your registry alone. It's not going to hurt anything having a tiny bit of data in your registry that isn't going to be used for anything anyway.)
There's not very much to say in regards to running HercGUI. Just fire it up (double-click on the Icon) and go! :)
A couple items of interest regarding the actual running of HercGUI should probably be mentioned however. The first is the 'Auto-Power-On' feature. If HercGUI is started with the command-line parameter:
-f <control-file>
then HercGUI will automatically 'Power On' Hercules once HercGUI is started (since you've already specified which Hercules control file you want it to use). Using this feature in conjunction which Hercules's .rc (run commands) file support, it is possible to totally automate Hercules startup and ipl.
For example, you could create a 'hercules.rc' file containing the necessary commands for starting your 3270 terminal sessions followed by a command to IPL your sysres, thus allowing you to automatically power-on and IPL your system by simply double-clicking on the HercGUI icon!
The auto-power-on feature is completely optional of course. The normal way in which HercGUI is used is by simply starting it first and then first manually selecting which device (hercules) configuration you want to use before powering on (this presumes of course that you have several different configurations). If you have only one fixed configuration you use all the time though, then the auto-power-on feature can come in quite handy. Simply create a shortcut with the "-f control-file" option added and voila! Automated startup. :)
The other "item of interest" is actually a caveat that should be mentioned: any "on the fly" changes you may make to your Hercules device configuration via the 'Device List' window pane's right-click menus (i.e. to add a device or remove or rename a device, etc) are TEMPORARY. Neither the configuration file that Hercules is using (nor the version that HercGUI maintains itself internally in memory) is actually changed.
Thus, if you do happen to make any temporary on-the-fly type changes as just described, you must remember to 'Save' your new configuration and/or 'Re-Open' the original configuration to discard your changes (if they were only temporary that is). The preferred manner in which to make changes to your device configuration is of course quite similar to the way you would do it on a real mainframe: by shutting down (powering off) your system first, and then connecting the new devices to it (or disconnecting old devices from it) before turning the power back on. :)
The various panels can be moved around the screen to suite you own personal taste. You can dock the Device List bar on either side of the screen or the various status bars on either the top or bottom of the screen. You can float them in a window by themselves, or you can hide them altogether. Your choice.
Just "grab" them with the mouse and drag them to wherever you want them to be. The screen layout is remembered across executions, so if you decide you like to have the Controls panel at the bottom of the screen, then just move it there. It'll be in there in the same place you left it the next time you start Hercules.
(click for larger image ~87K)
Starting with version 1.9.5 the Hercules/HercGUI Command-Line now allows you to specify the target directory that the
'sh' (shell) command should use. Simply browse to and select the desired directory.
Once set, any 'sh' (shell) command that is entered will be processed using the defined directory as its base (i.e. "current") directory. This is to allow for the fact that HercGUI's "current" directory constantly changes as directories are selected in its various dialogs, as well as to compensate for the fact that Hercules's current directory (prior to version 3.03) would normally never change. *
* The new 3.03 version of Hercules contains special support in the 'dyngui.dll' module for switching to the desired directory before issuing the 'sh' (shell) command that HercGUI sends to it.
The "Preferences" dialog is where you define your preferred directories, file extensions, logging options, etc.
- Directories
The "Directories" tab allows you to specify your preferred directories. The ones for 'Executable files', 'Configuration files' and 'Log Files' are the only ones that are required. The others are simply there for convenience and, if specified, are used as default directories by the various device configuration dialogs:
Some people found it easier to organize all of their tape, disk, reader, print, etc. files by having them all in separate directories. I do too now that I have that ability. Maybe you will too.
- File Extensions
The "File Extensions" tab allows you to specify your preferred file extensions to be used in the "Files of type" dropdown list-box in all standard Open and SaveAs dialog boxes that HercGUI uses:
This feature was added by request since each user may use a different file naming scheme for their reader, punch, configuration, disk, etc, files.
- Logging
The "Logging" tab allows you to specify your preferred console logging option:
The 'At Startup' option asks you for the filename of the console log file as soon as the GUI starts, whereas the 'At Shutdown' option waits until you close the GUI before asking whether or not you want to save the console log.
The 'Automatic' option doesn't ask you for a filename at all and instead generates a filename automatically based on the parameters you provide. If the base filename is "Hercules Logfile.txt" for example, the generated log file filename will be "Hercules Logfile.000.txt" the first time you start the GUI, and "Hercules Logfile.001.txt" the next time you start the GUI, etc.
Advanced Logging Option Starting with version 1.4.0, logfiles, once created (either via the 'At Startup' or via the 'Automatic' option), are written to continuously as new messages arrive, so the need to do periodic "Save Messages" is no longer necessary.
Also, because new messages are now automatically written to the logfile as Hercules runs and new messages arrive, you should be sure to specify (via the "Advanced Logging Options" dialog reached via the 'Advanced' button on the Logging tab) your desired maximum logfile size in number of lines. This is in order to prevent the logfile from filling up your hard drive:
The logfile is a wrap-around file wherein the oldest messages are overlayed with newer ones once the specified limit has been reached. Once the specified maximum number of lines have been written to the logfile, the GUI will reset its file position pointer back to the beginning of the file and begin writing new logfile messages over top of the older ones. The file is not simply recreated all over again. Once it wraps around when the limit is reached and begins overlaying older messages, the previous messages near the end of the logfile are still there. They're not lost, but they might of course be eventually overlaid just like the messages at the beginning of the file if enough new messages are written to cause it to wrap around for a second time, third time, fourth time, etc.Note too that the Advanced Logging Options dialog also lets you specify the maximum number of messages to be retained in memory (for scroll-back purposes) for the very same reason: to prevent run-away (unconstrained) memory consumption. This memory limit is a separate value from the disk logfile limit and essentially limits how far back you can scroll the console to see older messages.
- Console
The "Console" tab allows you to specify your preferred console font, font color and background color for the Hercules console message area:
Simply click on the appropriate button and select your font or color. Your selection will then be reflected in the sample edit-box to let you see what the console would actually look like before you actually apply your changes.
- Misc
The "Misc" tab allows you to specify various other miscellaneous preferences, such as how the GUI should react to your pressing the "Power Off" button:
About the "Shell command" option In my effort to try and add 'shell command' support to Herc for the Windows crowd (it already supported it for Linux but didn't work for the Windows version of Herc), I discovered a bug in the way Cygwin handles the 'fork' command, and while a workaround was being developed, I modified the GUI to be able to issue the 'shell' commands instead.
However, in order for the GUI to be able to issue shell commands instead of Hercules itself, I had to write a new program called 'conspawn.exe' that the GUI uses to pass the shell command to. The 'conspawn' program is included as part of the GUI package and must reside in the same directory as all the other Hercules executables.
Also, once the workaround to this Cygwin 'fork' bug was finally developed, I noticed that while Hercules could now issue the shell command itself (rather than have the GUI do it), it didn't seem to do it as efficiently (quickly) as the GUI could. Issuing shell commands via Hercules rather than the GUI seems somewhat "sluggish". I'd personally prefer to let the GUI do it, but since Hercules originally supported issuing shell commands itself (mostly for the Linux crowd), I thought I'd give you the option to choose for yourself which way you wanted it implemented.
The Ignoring Parse Errors option This option was created to allow you to open and use a Hercules control file that the GUI would otherwise complain about.
When a control file is opened, the GUI parses the statements and saves the information in an internal control area (so it can later use it to fill in the various fields of the various dialogs that it can display to the user, such as the device configuration dialog that allows you to modify a given device's properties for example), and if it cannot make sense out of a given control file statement (such as a device statement that contains a brand new parameter that Hercules understands but the GUI doesn't yet), it throws a parse error and prevents you from opening/using what it considers to be a bad control file.
The "Ignore Parse Errors" option instructs the GUI to ignore the parse error and open and use the control file anyway. This is to allow for the quite likely situation where Hercules is released with new device options and the GUI hasn't yet been updated to understand those new options. With the option set, the GUI ignores all parse errors and will always successfully open whatever control file you tell it to open. It is therefore highly recommended that you leave this option disabled and enable it only when absolutely needed.
If you do ever enable it, please remember to disable it when you no longer need it. The GUI will not do that for you. Once you enable it, it stays enabled until such time as you purposely disable it -- even across subsequent executions of the GUI (just like all the rest of the preference options, it is a persistent (i.e. "sticky") option).
- Misc2
The "Misc2" tab continues with additional options that wouldn't fit on the original Misc options tab:
Special command-line arguments Starting with the 3.0 version of Hercules, Hercules now supports additional command-line options above and beyond the existing -f option used to specify which control file to use. Here you can enter any of the new command-line options you may wish to have specified whenever the GUI starts up ("Powers On") the Hercules emulator. You must not specify the -f option here however! The GUI constructs the -f option automatically based on the currently opened configuration file so you must not specify it here. You may however enter here whatever other command-line options you may need in addition to the required ones. (See important note immediately below)
Important!
This is an "advanced" option and you should normally not need to modify it at all unless you are very sure you know what you are doing (or if so instructed by Hercules "Technical Support Personnel" (i.e. one of the Hercules developers)).
When you open a Hercules control file (I seem to flip-flop between calling it a control file and a configuration file, sorry; to me the terms are interchangable) the GUI parses it and then displays a "System Configuration" dialog showing you the various configuration settings.
Beginning with version 1.11.0, the System Configuration dialog information is spread across four separate property pages: the Architecture page, the O/S Tailor settings page, the Other/Misc page and the Advanced page.
The Identification section simply displays the full pathname of the configuration file that you've opened as well as providing an input field where you can enter a personal description of what this particular configuration file is for. This is in case you have multiple system configurations and you want to be sure you're modifying the correct one. The description you enter here is saved as a comment at the beginning of the configuration file.
- Architecture settings
This page of the System Configuration dialog is where you would define various hardware architectural settings, such as how many emulated CPUs you want your virtual mainframe to have, how much emulated main storage, etc:
The Architecture radio buttons allow you to define what architectural mode your emulated CPUs should be initially placed into by default. For emulated zArchitecture machines, the actual IPL always takes place in ESA/390 mode and is the responsibility of the IPL'ed operating system to switch the CPU(s) over to zArchitecture mode (via the appropriate SIGP instruction) whenever it is ready for them to actually run in that mode.
CPU Model number On the main System Configuration dialog, a small '>' button will appear next to the "CPU Model number" edit-box, if, and only if, the GUI finds a specially formatted file called cpu-types.txt in your preferred Configuration Files directory.
This file contains all of the various CPU model numbers and names and their corresponding STIDP ("Store CPU ID" instruction) values that I could find. (As you may or may not recall, I was asking about that on the main Hercules-390 list a while back. Now you know why.)
When the System Configuration dialog is initialized, if the GUI finds this file, it will read it and parse all of the entries contained in it and use them to construct a drop-down combo-box that's displayed whenever you click the '>' button, which then allows you to easily select the desired CPU Model you wish your virtual mainframe to be reported as.
Note: Neither the GUI nor the Hercules emulator itself makes any attempt to try and emulate all aspects and/or features of a given CPU model. The CPU model number simply specifies what value to use in the STIDP (Store CPU ID) instruction, and nothing more.
When your CPU Model is selected in this way, the GUI automatically fills in the "CPU Model number" edit-box field with the corresponding value it finds in the "cpu-types.txt" file.
Of course, you always have the option of manually changing the value to whatever the heck you want, but for those people who don't happen to know (or remember) what the proper CPU model# value is for the particular model of mainframe that they used to play on years ago, then this feature should prove to come in quite handy. It's just a little thing, but it does make Hercules a little bit easier to use and a tad bit more user-friendly. <shrug>
A sample cpu-types.txt is included with the distribution. If you find any problems with it (any incorrect values), then I'd appreciate it if you'd please let me know about it so that I can have it corrected for the next release. Thanks.
- O/S Tailor settings
The O/S Tailor settings page is where you define certain settings related to the flavor of guest operating system you intend to actually run on your virtual mainframe. The purpose of the O/S Tailor radio buttons is to simply limit the amount of Hercules generated message traffic by asking it to selectively suppress certain "Program Check" type trace messages which are usually considered normal for the specified operating system:
"Enable Licensed Program Product O/S" When this option is specified for a given control file, then attempts to power on Hercules using that control file will result in a dialog box being displayed asking you to verify your true intentions:
Once the dialog is displayed, a 10-minute timer is started. If you respond before the 10-minutes expires, your response is accepted as-is.If your response is "No, I do NOT honestly wish to run in unrestricted mode", then your virtual mainframe will NOT be Powered On.
If your response is "Yes" -- whether explicit or presumed, it doesn't matter (see next paragraph) -- then Hercules (i.e. your virtual mainframe) will be Powered On.
Please note that if you fail to respond within the 10-minute time limit, then your response is presumed to be "Yes, I honestly DO wish to run in unrestricted mode", but you of course have to wait for the 10-minute timeout to occur before such a response will be presumed. If you don't wish to wait the entire 10 minutes then you will have to respond to the dialog manually yourself. There is no way to disable or override this feature.
This dialog is displayed each time you attempt to power on Hercules during a given HercGUI session when using a configuration file with the "Enable licensed program product O/S" option checked ...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.
. . . until you respond to it.
Once you have explicitly responded "Yes" to it, however, then the GUI will power on Hercules immediately from then on (for the selected configuration file) for that HercGUI session. As long as you continue to use that particular configuration file during that HercGUI session, you will be able to power on and power off and power on, etc, as many times as you like without the dialog being displayed. If you switch to a different configuration file, however, and then come back to that same one (or exit the GUI entirely and then start it back up again), you will then of course be asked to once again confirm your actual intent.
- Other/Misc settings
The Other/Misc page allows you to define even more system configuration values related mostly to the actual internal functioning of the Hercules emulator itself. Please refer to the actual documentation for the Hercules emulator itself for more information regarding the various values that may be specified here:
CONKPALV Starting with Hercules version 3.05 you can now specify your 3270 console connections "keep-alive" settings:
The values you enter here control the automatic disconnection of inactive/unresponsive console connections, and allows TSO sessions that were disconnected due to communications failure to reconnect to their previous sessions.For details regarding acceptable CONKPALV parameters values and their meaning please refer to the appropriate Hercules documentation.
Shared Dasd Server Hercules "Shared Devices" support allows multiple Hercules instances to share devices. The device will be 'local' to one instance and 'remote' to all other instances. The local instance is the 'server' for that device and the remote instance is the 'client'. The SHRDPORT statement 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. For further details regarding the Hercules Shared Device Server please refer to the Hercules documentation.
Enable HTTP Server support Hercules's HTTP Server support allows you to control Hercules via any standard web browser. This dialog allows you to define the HTTP Server parameters that Hercules is to use:
Enter the desired port number you wish Hercules's HTTP Server to use, and then specify (if desired) the authentication criteria needed to connect to it, as well as the "root" (base) directory where the web pages will be served from.Note: If you enter a userid then you must also enter a password. If no userid/password is entered then anyone with a browser who is able to connect to your Windows host system will be able to control your Hercules system through the HTTP Server interface.
Note: the password you enter is not encrypted in any way, and is in fact both stored in your Hercules control file, as well as passed through the network, in unencrypted plain text format. You should therefore take whatever steps are required to secure any/all Hercules control file(s) which contain HTTP Server passwords.
CCKD parameters Starting with Hercules version 2.17, the behavior of Hercule's compressed CKD dasd functionality (CCKD) is controlled via the setting of certain global parameters which affect the CCKD functionality of all CCKD dasd. (In other words, CCKD functionality is no longer adjustable on an individual device-by-device basis. Instead, you adjust global CCKD parameters via the CCKD Parameters dialog which affects the functioning of all CCKD devices):
If you enter/enable CCKD parameters via this dialog, then certain other controls on the Dasd Device dialogs (see next section further below) will not be displayed. This is because, as explained, the new global CCKD parameters now override (obsolete) the old (pre-2.17) individual device parameters. For details regarding the acceptable CCKD parameters values and their meaning please refer to the appropriate Hercules documentation. - Advanced settings
The Advanced configuration page is where settings for features that are intended only for more advanced users may be made. If you have a custom dynamic module (DLL) you wish Hercules to use or wish to modify Hercules's default priority settings you would do that here.
Clicking the "Devices" button from the System Configuration dialog (or selecting "Modify Devices" from the 'File' menu) will take you to the "Device Configuration" dialog where you can add, delete or modify the devices in your current configuration. This particular dialog is resizable since device configuration statements can potentially be quite long:
The purpose of the "Maximum shutdown wait time expected for this configuration" setting is to inform the GUI approximately how long of a delay to expect between the time you issue the 'quit' command (or click the "Power Off" button, same thing) and the time when Hercules finally finishes exiting after beginning its shutdown sequence.
When you use compressed disks, Hercules needs time to write out its cached copies of track images and adjust the free space for all the compressed disks before it can safely exit. If the specified expected time value is exceeded, the GUI warns you and then asks whether you wish to continue waiting a little longer or forcibly terminate the Hercules emulator process.
If you have many compressed disks that are updated frequently, Powering Off could take anywhere from 10 to 60 seconds or more, and the GUI needs to know whether or not the delay is expected or not (to allow for the possibility -- however remote -- that the Hercules emulator process gets hung).
Of course, if Hercules finishes shutting down before the specified time period expires, then the GUI powers off immediately.
Right-clicking on a device statement presents you with a context menu from which you can select either 'Edit' or 'Properties'. Selecting 'Properties' presents you with a "Reinitialize Device" dialog identical to the one that is displayed by double-clicking on a device statement. (See a little bit further below)
The 'Edit' right-click function is new. When you select 'Edit' from the right-click context menu, you are presented with a simple device statement edit dialog where you can directly modify the raw device statement itself:
To add a new device, simply click on one of the 'Add' buttons:
To delete a device, simply select it first to highlight it, and then click on the "Remove" button.
To modify a device, just double-click on the entry for the desired device:
Note: If you entered (enabled) any of the new CCKD parameters on the main System Configuration dialog (see previous section further above), then certain controls on the above dialog will not be displayed. This is because the new System Configuration CCKD parameters modify CCKD functionality on a system-wide basis and override (obsolete) the ability to specify such parameters on an individual device-by-device basis.
The 'Display/Alter Storage' item in the Command menu allows you to display and/or alter absolute main storage.
Note! If you need to modify real or virtual storage it is strongly recommended that you instead use the Hercules 'r' and 'v' commands so that the 'hardware' (i.e. the Hercules emulator) knows about it!
It's very important that you keep in mind that when you alter absolute main storage via this dialog that neither the storage keys nor the CPU instruction and data caches are updated in the emulator itself. The memory of the Hercules process is directly modified without the Hercules emulator even knowing about it, so please use this feature with caution. It is mostly designed for examining (searching) main storage and for other emulator debugging purposes and not as a safe means of modifying operating system storage.
These menu items (in the Operations menu) provide a quick and easy way to do just what they say. The 'Load Reader' command is especially handy in "submitting" jobs to the system. All it does is display the "Re-Initalize Device" dialog for the card reader where you can use standard Windows 'Open' dialogs to browse for the file you want to 'submit' (i.e. load into the card reader). Clicking OK then issues the appropriate Hercules 'devinit' command.
The "(input data is from socket)" option (to the right of the device type field) allows you to specify that Hercules should obtain card reader input from a specified socket instead of a disk file like normal. This allows you to submit card decks remotely via a simple utility that connects to the specified socket and writes the data directly to Hercules. HercGUI comes with a command-line program called "HercRdr" that does just that. For more information on the HercRdr utility (and the 'sockdev' option itself), please refer to the "Card reader devices" section of the Hercules Configuration web page.
The Device List bar, just like its non-GUI (console mode) counterpart, lists all of the devices in the current configuration and their current status.
A gray diode indicates the device is offline (not open), whereas a green diode indicates it's online and/or open. The green diode changes to yellow whenever the device is busy and changes to red whenever there's an interrupt pending for it. As the system runs and does I/O to the various devices in your configuration, you'll see the diodes change between yellow and red and green and this simply means that there is I/O activity taking place on that particular device.
Each device is kept in a separate branch of the tree-list according to the class of device that it is, and each entry in the list -- including the device class branches themselves -- present a right-click context menu whenever you right click on it.
If you want to add a new disk drive to your configuration, for example, simply right-click on the "DASD Devices" branch and select 'Add device' from the menu that appears.
To delete ("detach"), rename ("define"), reinitialize ("devinit") or present an attention interrupt ("i") for a particular device, simply right-click on it and select the appropriate menu item from the context menu that appears.
All of the utility programs can be run by simply filling out the appropriate dialog with the desired options and clicking OK. The utilities (and Hercules itself for that matter) all run as a separate process so you can run more than one, and Hercules too, at the same time.
A progress dialog is displayed as the utility runs so you can track how far along it is, and all messages generated
by the utility are displayed on the gui console just like the Hercules messages are. Each message is prefixed with
its process id and a timestamp so you can know which messages are for which program.
Some of Hercules's current minimum, maximum and default values that HercGUI uses in its various dialogs are kept in the Windows registry. This is mostly for ease of program maintenance on my part since, if any of them change, I can then simply tell all my customers/users to make the same corresponding change to their registry values without me having to build and ship each of them a brand new version of HercGUI.
What follows are the various values that HercGUI uses to control the minimum and maximum allowed values that one can input into certain dialog controls.
Please note that changing the below values will not necessarily change the actual functioning of the Hercules emulator itself! (since even if the GUI accepts the new values that doesn't necessarily mean Hercules itself will)
All of the below values (except for the 'MinTODDrag' and 'MaxTODDrag' values (which are string
values)) are DWORD values, and all of them are kept in the 'Limits' branch of the main HercGUI registry key:
HKEY_CURRENT_USERS/Software/Software Development Laboratories/Hercules/Limits
|
softdevlabs.com