ConfiguringTheEmulator - pkimpel/retro-1620 GitHub Wiki
Configuring the retro-1620 Emulator
This page describes how to configure the system and peripheral devices for the emulator.
The Configuration Window
The emulator home page has a button below the picture of the 1620 system labeled Configure System.
Clicking that button opens a sub-window that shows the current system configuration and allows you to change it. The button is enabled -- and the configuration can be accessed -- only when the emulator is in a powered-down state. This is the state immediately after loading the home page into your browser or after double-clicking the POWER switch on the Control Panel to shut down the emulator.
The configuration sub-window is rather large, and will scroll on most displays. It looks similar to the following:
This window has areas for selection of global system properties and input/output peripheral devices. You can change the configuration by altering the controls in this window and clicking the SAVE button. If you only want to view the configuration or discard any changes you have made, click CANCEL. Both buttons close the window.
The DEFAULTS button will discard the current configuration and replace it with the default one described in the next section.
The CONFIGURATION EXPORT/IMPORT button will open a panel over the window to all you to save the current system configuration (optionally including disk drive images) to a file and later restore that file to the same or a different workstation. See the section "Exporting and Importing Configurations" below for details.
Persisting the Configuration
The configuration data for the emulator is saved using an HTML5 feature known as Local Storage, implemented in Javascript by the window.localStorage
object. Local Storage is supported by reasonably recent versions of all the major browsers. It allows a web page to store information that will persist across browser sessions and workstation restarts. For example, Firefox stores this data in a SQLite data base on your local disk drive.
Data in Local Storage is subject to the browser's same-origin policy, meaning that separate copies of the data are maintained for each combination in the URL scheme (http/https), host name, and port number. Thus, if you are accessing the emulator on two different web sites, you will have a different copy of the configuration data for each one.
The host name is taken literally. For example, you can access the emulator on the hosting site either at https://www.phkimpel.us/IBM-1620/ or at https://phkimpel.us/IBM-1620/. Both URLs will access the same physical files on the server, but those are different origins as far as the browser is concerned. In addition, Local Storage data is maintained differently by different browsers, so if you use the emulator with, say, both Firefox and Google Chrome, each browser will have separate Local Storage data.
When you first run the emulator in your browser, the emulator will recognize that no configuration data is present, and will automatically create a default configuration for you. This is the same configuration established by the DEFAULTS button on the configuration page:
- 40,000 digits of memory
- No index register, floating point arithmetic, binary capabilities, or persistent window positions.
- IBM 731 Selectric typewriter
- IBM 1622 card reader/punch
- No line printer, disk devices, or other I/O devices.
The following sections discuss the areas of the System Configuration window and how you use them to specify the set of peripherals to be included in your 1620 system.
System Properties
This section discusses the emulator's global system properties.
Memory Size -- Using this pull-down list, you can select the amount of memory the emulator will use: 20,000, 40,000 or 60,000 digits. Attempting to access memory locations beyond the size set in the configuration will result in the emulator halting with a MAR check stop.
Index Registers -- Ticking this check box will enable index register functionality and the instructions BLX, BLXM, BSX, BX, BXM, BCX, BCXM, and MA. When the box is unticked, these instructions are invalid and will cause a MAR check stop. In addition, flags over the middle three digits of instruction P and Q addresses will be ignored during the I-cycles of instruction fetch.
Floating Point -- Ticking this check box will enable floating point arithmetic functionality and the instructions FADD, FSUB, FMUL, FDIV, FSR, and FSL. When the box is unticked, these instructions are invalid and will cause a MAR check stop.
Binary Capabilities -- Ticking this check box will enable the binary instructions BBT, BMK, ORF, ANDF, EORF, CPLF, OTD, and DTO. When the box is unticked, these instructions are invalid and will cause a MAR check stop.
Persistent Window Positions -- By default, the emulator will size and position its windows at locations on your primary (or only) workstation display as determined by the size of the display. Ticking this check box causes the emulator to remember each window's position and reinstate the windows in those positions the next time the emulator is initialized.
Use Multi-Screen Positioning -- This option is enabled only when the Persistent Window Positions check box is ticked. It is effective only when your local workstation has multiple displays and your browser supports the Window Management API. As of this writing, the standard for the API is in draft status and only Google Chrome supports it. As a result, the emulator's handling of multiple monitors is both browser-dependent and somewhat complex. See "Multiple Display Window Positioning" below for details.
Input/Output Devices
This section discusses configuration of the emulator's input/output devices.
731 Typewriter
The console typewriter is part of the standard 1620 system configuration; most 1620 software will not work properly without it. The System Configuration window displays the settings for the typewriter's margins, number of columns, and tab stops, but these are set on the typewriter's window after the emulator initializes. By default, these settings are:
- Margin-Left 0
- Margin-Right 80 (i.e., an 80-column width, max is 85)
- Tabs at columns 9, 17, 25, 33, 41, 49, 57, 65, 73, and 81.
For details, see Using the Typewriter.
1622 Card Reader/Punch
The 1620 card reader and card punch devices were packaged together in one cabinet. Internally, they are all but completely mechanically and electrically separate, but are included or excluded in the configuration as one. There are two options that can be selected on the System Configuration window.
Reader/Punch Speed:
- None excludes both units from the configuration.
- Model 1: 250/125 CPM selects 1622 Model 1 speeds -- 250 cards/minute read, 125 cards/minute punch.
- Model 2: 500/250 CPM selects 1622 Model 2 speeds -- 500 cards/minute read, 250 cards/minute punch.
Punch Stacker Capacity determines the number of cards that can occupy the punch's output stacker before a stacker-full condition occurs and the punch is made not ready. The value of this field can range from 100 to 999,999. For details, see Using the Card Punch.
1443 Printer
The 1620 line printer has these settings:
Printer Speed:
- None excludes the unit from the configuration.
- Model 1: 150 LPM selects 1443 Model 1 speed with a 52-character type bar -- 150 lines/minute.
- Model 2: 240 LPM selects 1443 Model 2 speed with a 52-character type bar -- 240 lines/minute.
Columns selects the number of print columns, 120 or 144. Note that the version of the Monitor I operating system available from the Computer History Museum supports only 120 columns.
The window displays the current carriage control tape configuration, but this is set on the printer's window after the emulator initializes. It defaults to a carriage tape of infinite length (i.e., no channel 9 or 12 punches to designate end-of-page) and all channel skips acting as a skip to top-of-form. For details on preparing and loading a carriage control tape, see Using the Line Printer.
1621 Paper Tape Reader
The only setting for the paper tape reader is to include or exclude the device from the configuration.
1624 Paper Tape Punch
The only setting for the paper tape punch is to include or exclude the device from the configuration. Note, however, that the punch and the 1627 plotter use the same connection to the CPU, so only one of them can be included in the configuration at a time. When the plotter is enabled, the option to enable the paper tape punch is disabled, and the plotter must be disabled before the punch can be enabled.
1627 Plotter
The 1620 plotter has these settings:
- None excludes the unit from the configuration.
- Model 1: 11-inch carriage includes the unit in the configuration.
The plotter has an option to scale the plot. The default 50% setting draws two plotter steps per screen pixel. The 100% setting draws one plotter step per pixel, but this causes the plotter window to be almost twice as wide on the screen as compared to the 50% setting, unless the Persistent Window Positions option described above is selected, in which case the window's retained size will be used. See the Using the Plotter wiki page for more information on plot orientation and scaling.
As mentioned above for the paper tape punch, the plotter and punch cannot be included in the configuration at the same time. When the punch is enabled, the option to enable the plotter is disabled, and the punch must be disabled before the plotter can be enabled.
1311 Disk
The 1620 disk subsystem supports up to four disk modules. Module 0 must exist in order for any other modules to be recognized. Any combination of modules in addition to Module 0 may be configured. Each module has three check boxes to control its behavior:
- Exists -- if this box is ticked, the module is included in the system configuration. If this box is unticked, none of other check boxes for that module are relevant.
- Started -- If this box is ticked, the module is powered on. It corresponds to the START/STOP button on the disk control panel.
- Enabled -- If this box is ticked, the module is enabled for reading and writing. It corresponds to the ENABLE switch on the disk control panel.
All three check boxes must be ticked in order for the module to be usable by the system. Changes to the Started and Enabled check boxes are reflected in the settings on the disk control panel and vice versa. The states of all three check boxes are preserved across emulator restarts.
The Image setting on the window shows the name of the disk pack image file last loaded to the module. If the module was initialized via the disk control panel, this will read (initialized)
.
For details, see Using the Disk Drive. Note that enabling index registers can cause problems in the Monitor I operating system due to the way that Monitor I was not careful about allowing flags in address digits. You may wish to disable index registers when using Monitor I.
Exporting and Importing Configurations
The System Configuration window allows you to export a complete definition of the emulator's current configuration, optionally including the data for the disk units, to a file on your local workstation. You can use this as a backup for your emulator instance, or to maintain multiple configurations and switch among them, or to transfer a copy of your configuration to another web browser or workstation.
To access this feature, click the CONFIGURATION EXPORT/IMPORT button in the upper-right corner of the window. This will open a panel on top of the window:
The system configuration is formatted as a JSON (JavaScript Object Notation)[https://www.json.org/json-en.html] file. You can export the configuration as a JSON text file, or you can export it as a compressed zip file that contains the JSON text file. Either type of file can be imported directly back into the emulator.
If the check box at the top of the panel is ticked, the export will include disk images for all disk units that exist in the configuration; otherwise the export will contain only the system configuration. If drives exist, their images will be exported, even if they are not started or not enabled. After a successful export, the Export/Import panel will close automatically.
To export the configuration as JSON text, click the Export as JSON button on the panel. To export a zip file, click the Export as Zip button. A configuration exported as text, without disk image data, is about 5KB in size. An export with one minimal disk image is about 2.4MB and zips down to about 250KB. An export with two such images is about 4.8MB and zips down to about 500KB.
To import a configuration file, click the Browse or Select Files button (depends on the browser) on the panel and select the appropriate file, which must be have a file name extension of either .json
or .zip
. Selecting the file automatically starts the import, which will unzip the file internally if necessary. You will receive a confirmation alert asking if you want to replace the entire configuration. Disk images will be loaded/replaced only if:
- The check box at the top of the Export/Import panel is ticked.
- Disk drives exist in the configuration.
- Disk module #n (n=0-3) exists in the configuration and a corresponding image for that module is present in the import file.
Any errors in the export or import process will reported as alert pop-ups. Additional information on the export and import processes is written to the JavaScript console, which can be viewed by opening the browser's developer tools (F12 key in Firefox and Chrome). After a successful export, the Export/Import panel and the System Configuration window will close automatically. The reason for closing the window is that it no longer shows the correct configuration. Simply reopen the window if you need to make further changes to the configuration.
The JSON file has two main parts: The first is the SystemConfig
object that represents the system configuration, and is always present. This is simply a copy of the data that the emulator persists in the browser.
The second part, which is optional, is DiskModule
. It will be present only if the check box at the top of the Export/Import panel is ticked and disk drives exist the configuration. If present, it is a two-dimensional array. The first dimension is indexed by the disk module number (0-3) and represents the data for one disk image. The second dimension is an array of strings, one string per disk sector.
The exported JSON or zip files can have any name you wish, but within a zip file, the JSON file must have the name retro-1620-Config.json
. When importing a zip file, the emulator will look for that specific name and only unzip that file. If a file with that name is not present in the zip file, the import will fail. Otherwise, there is nothing special about the zip file, and you can create the zip file from a JSON export file as long as the JSON file has the required name inside the zip file. Any other files within the zip file will be ignored by the import process.
The export file is intended to be used only by the import mechanism. It is possible to edit the JSON file manually using an ordinary text editor, but we strongly recommend that you do not do so. The emulator depends on the configuration data having a certain format and its items having specific values. The import process does some limited validation of the data during import, but it is more in the nature of a sanity check than an attempt to validate the file. If you edit the file and mess something up, the best you can hope for is that the emulator will just ignore it. The worst you can expect is that the emulator won't run correctly, or possibly won't run at all.
Multiple Display Window Positioning
By default, the emulator will automatically determine the size and position of the Control Panel and I/O device windows on your workstation display. If you resize or move the windows, these changes will not be preserved across an emulator restart, and the windows will be placed at their automatic positions the next time the emulator is initialized.
Two check boxes discussed above under "System Properties" control the persistence of window sizes and their positioning:
- Persistent Window Positions
- Use Multi-Screen Positioning
If both check boxes are unticked, the emulator uses its default automatic window sizing and positioning method.
If the Persistent Window Positions check box is ticked, the emulator will remember the size and location of each window across an emulator restart, but the way this works depends on whether your workstation has multiple display devices and whether your browser supports the Window Management API. The Use Multi-Screen Positioning check box is relevant only if (a) Persistent Window Positions is ticked, (b) your workstation has multiple display devices, and (c) your browser supports that API.
As of this writing, only Google Chrome supports that API, the specification for which is still in draft status. Therefore, the following information and the emulator's behavior may change unexpectedly as standardization of the API proceeds. For now, the behavior can be described in two parts, one for Chrome and one for all other browsers.
The emulator maintains window position and size information for each of its windows under three "modes":
-
Auto -- this is the default, and is used when Persistent Window Positions is not ticked. Windows will be positioned and sized by the emulator. Any changes to window size or position will not be preserved across emulator restarts.
-
Single -- this is enabled when Persistent Window Positions is ticked in the configuration and Use Multi-Screen Positioning is not. This causes the current window positions to be preserved when the emulator is powered off and then reinstated the next time the emulator initializes, but the way this works currently differs between Chrome and the other browsers, as discussed below.
-
Multiple -- enabled when Persistent Window Positions and Use Multi-Screen Positioning are ticked in the configuration, your workstation has multiple display devices, and the browser supports the Window Management API. This is intended to support multi-monitor configurations.
The emulator persists window size and position information across emulator restarts separately for Single and Multiple modes, but not Auto mode. This allows you to maintain different window configurations for single- and multiple-display workstation configurations, e.g., a laptop that you use at your desk with one or more additional displays, but also standalone with only the laptop's screen.
If neither check box is ticked, the browser will use "Auto" mode positioning. Windows will be positioned automatically. If you have multiple monitors, the windows should be placed on the same display as the main window.
Ticking Persistent Window Positions will enable "Single" mode positioning. The sizes and positions of the windows will be saved when the emulator is powered off, and the emulator will attempt to restore the windows to those positions the next time it is started.
-
Under Chrome, when the Multi-Screen box is not ticked, the windows will all be placed on a single display, regardless of how many displays are present. You can move windows to other displays, but they won't be restored there.
-
Other browsers, however, will consider the multiple displays to be one contiguous space. Thus, you can move the windows to other displays, and those browsers will attempt to restore those windows to their former positions in the contiguous display space. If you later remove a display and restart the emulator, the browser will constrain the window positions to the newly available display space.
Ticking Use Multi-Screen Positioning will attempt to use "Multiple" mode positioning by means of the Window Management API. At present, this is the only way for Chrome to be able to restore windows to multiple displays. This setting will only be effective if (a) the Persistent Window Positions check box is ticked, (b) the browser supports the API, and (c) the workstation currently has multiple displays. If all those conditions aren't met, the emulator ignores the Multi-Screen check box and reverts to either "Auto" or "Single" mode positioning, depending on the setting of the Persistent check box. At present, the Multi-Screen check box will be ignored for any browser other than Chrome.
By default, Chrome is supposed to prompt for permission to use the Window Management API when you first try to use the API, but for some reason the prompt never appears. Instead, Chrome throws an exception. Since this is quite a new API, it's probably a bug.
Fortunately, there's another way to get the permission granted:
- Open Chrome's settings panel from the 3-dot icon on the right of the address bar (or you can enter
about:settings
in the address bar and press Enter). - From the "Settings" menu on the resulting page, select "Privacy and Security."
- On the next view, select "Site settings."
- On the next view, expand "View permissions and data stored across sites."
- Select "www.phkimpel.us" or "phkimpel.us" (or whatever site you're running the emulator from). There's a search box in the upper-right corner if the list shows a lot of sites.
- On the next view, scroll the list of permissions to "Window management." On the right of that is the current permission (probably set to "Ask").
- Change the permission to "Allow." The change takes effect immediately.
You could also try this method, which may be quicker:
- Open the Developer Tools (F12 or via "More tools" on the 3-dot menu).
- Click the "Console" tab.
- At the command prompt, enter
await window.getScreenDetails()
and press Enter. A prompt should appear over the main window (make sure it's not covered by the Developer Tools window). Click the "Allow" button. - Close Developer Tools.
This window positioning scheme is a little complex, but is designed this way in an attempt to have sensible behavior when the workstation's display configuration changes. It also gives you the ability to opt out of using the Window Management API and having to worry about its permissions. You only need to give permission for the Window Management API once per origin from which you load the emulator, but some users may want to run in Single mode even if they're running Chrome and have multiple displays.