Installation involves simply unzipping the executables into a folder of your choice. There is no special installation program required. Uninstalling is pretty much the reverse: just delete everything.
Note however that I do add a new key to your Windows registry to hold some configuration settings and such, so if you really want to completely rid yourself of my program, 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 ever going to be used anyway.)
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 where you want them to be.
(click for larger image ~ 71K)
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.
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).
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:
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.
Starting with version 1.4.0, the "ESAME" Architecture option is now enabled and can be selected if so desired. However, please be aware that even though the ESAME architecture mode is now allowed (letting you run Hercules in 64-bit mode, which you could always do anway; only the GUI didn't support it but Herc always has) (well, ever since version 2.0 anyway), I haven't yet had a chance to update the registers display panels to support (display) the new wider (64-bit) registers values, so they'll probably be pretty much useless to you in 64-bit ESAME mode (if they even work at all! They might not; I don't really know. I haven't actually tested it since I personally don't have a 64-bit operating system that I can test with).
Don't ask me why I spent all the time I did doing this (I guess I'm just the type of person that feels it's important to try and make programs as user-friendly as they can be I guess. Call me a perfectionist if you want, but that's just the way I am. <shrug>), but what I did was this:
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 you can then use to select your desired CPU Model.
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, nothing more.
When your CPU Model is selected 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, and if you find any problems with it (or any incorrect entries), please let me know about it so I can correct it for the next release. Thanks.
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 you fail to respond within the 10-minute time limit however, then your response is presumed (with the default presumption being "Yes, I honestly DO wish to run in unrestricted mode.").
If your response is "No, I do NOT honestly wish to run in unrestricted mode", then Hercules is NOT powered on.
If your response is "Yes" however -- (whether explicit or presumed, it doesn't matter) -- then Hercules will be powered on.
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) ...
. . . 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, you will then of course be asked to once again confirm your intentions.
Clicking on the "Devices" button from the System Configuration dialog (or selecting "Modify Control File | 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 quits (i.e. finishes shutting down and exits).
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 process becomes hung).
Of course, if Hercules finishes shutting down before the specified time period expires, 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, select it first to highlight it, and then simply click on the "Remove" button.
To modify a device, double-click on the corresponding entry:
Note: you cannot change the device number or device type for existing devices. If you want to change the device number or device type, you must delete the device and then re-add it under the new number/type.
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 cache 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. I've included as part of this release of the GUI 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.
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.