REFDoor 1.2 Release

I’m publicly releasing version 1.2.0 of my REFDoor REF scripting engine door today!

This release contains all kinds of bug fixes, some new commands, and a slew of behind the scenes optimizations and improvements including changes which should greatly improve REFDoor’s performance when running on retro hardware. The most notable under the hood change is the addition of what I’m calling “memory mode” which behaves very similar to the original RTSoft RTReader by reading the entire script into memory for faster parsing and less disk activity. This may seem incredibly draft to the few of you who read my REFDoor 1.0 article and/or its included documentation and recall that the whole reason I developed REFDoor was specifically to see if I could mimic the entirety of the original parser’s behavior without reading the file into memory, but as I have vague aspirations to use REFDoor as the engine behind a future door game project of some sort, I want to implement as many options and improvements as possible.

Here’s the entire WHATSNEW.TXT file (which includes the unreleased 1.0.1 and 1.1.0 versions) for reference:

REFDoor v1.2 What's New?
---

 ! = Bug Fix
 + = Additions / Changes
 - = Removed
 * = Additional Notes


v1.2.0 - Released 02/12/2021
---

 + Added "DO CENTERPAD" command which works similarly to DO PAD and DO FRONTPAD
   but centers the string within the specified length (defaults to 80 if not
   specified) padding out the string with spaces on either side. Similar to
   "CENTER" but potentially more useful for things like title strings with
   different backgrounds, etc.
 + Added the "IS CHAR" function to the "DO" command. This function will allow
   you to return the character at the specified position from the provided
   string. Until now, you haven't been able to access characters from strings
   in REF. This should help with enable numerous string operations that would
   have previously only been possible with built-in REF commands.
 + The "SHOW SCROLL" command now optionally accepts a parameter pointing to
   an external file to display instead of parsing the "SHOW SCROLL" text
   inline.
 + Added a clean up procedure to REFDoor's startup to clean out any orphaned
   temporary file for the node being launched. In most cases this won't have
   fixed anything since most routines check for these files and remove them
   before generating a new one.
 + Added "memory mode" which loads the entire script into a memory buffer. On
   some systems this will be dramatically faster than the default line-by-line
   text parsing and with no IO hit, though on some it may not actually improve
   performance. Memory mode requires at least 64K of convential memory free
   and maxes out at around 640K per file. When using commands like "RUN" or
   "ROUTINE" to call other scripts, memory will be swapped. Memory mode is
   available by using the "/M" command line parameter.
 + Added label mapping when using memory mode - when a script is first launched
   (or reloaded after a swap) the label positions in the script are mapped into
   memory to make "DO GOTO" calls much faster on slow machines. The traceoff is
   that slow machines will also see a 1-2 second delay while this is happening.
   Semi-modern machines won't even notice.
 + As such, "NOCHECK" command as been made functional. This disables the memory
   mapping functionality from when it is encountered on. I'd highly recommend
   NOT using this for anything but very simple scripts (at least on slow
   machines - it shouldn't make much difference on semi-modern machines!)
 + Added an alternate version of "SHOW SCROLL" which parses a text file to
   memory when using memory mode. This version looks identically but allows
   line scrolling using the up and down arrows, has instant file export, and
   the find command results in the exact line of the next hit rather than just
   loading the page. The memory mode "SHOW SCROLL" should result in
   dramatically improved performance when loading massive amounts of text on
   slower machines.
 * If you're running into memory mode / memory usage issues, REFDoor logs some
   potentially helpful details about memory availability and usage. Use the
   new /V switch to see them.
 ! Fixed a display issue with the status bar in "SHOW SCROLL" when viewing a
   larger number of pages. Changed the entire layout of the status bar to
   compensate - while its no longer identical to RTReader, it still looks
   very similar.
 - The 16 bit DOS compatible executable no longer uses an overlay file. It was
   used before to leave the maximum amount conventional memory free but due to
   the way REFDoor is structured, resulted in extremely bad performance on
   older (386, 486, etc.) machines. I may revisit this in the future as it
   would allow for a larger buffer to be available when operating in memory
   mode, however, RTReader worked the same way, so this shouldn't be a massive
   negative. I would love to know if this change negatively impacts you!
 ! Fixed a bug related to page up/page down key detection, which particularly
   impacted the "SHOW SCROLL" commands.
 ! Fixed a very isolated bug where REFDoor's ANSI parser would process display
   codes if they were at the beginning of a line right after a CRLF on the
   previous line, *before* showing the MORE prompt for that line during a
   @DISPLAY or @DISPLAYFILE command, thus sometimes messing up the MORE
   prompt's display. This only fixes invalid codes - valid codes can still
   potentially be parsed this way, causing some odd behavior in rare instances
   - it's unlikely you'll be displaying files with control codes besides colors
   this way in the first place. Unfortunately a complete fix would require
   rewriting the ANSI parser (which I should probably do one of these days.)
 + Various logging changes including logging exit codes / error levels when
   a halt is issue, as well as a revised exit code scheme.
 + Added "SCROLLTOP" which lets you define where the SHOW SCROLL window starts.
 + Added "SCROLLSIZE" which lets you define how many lines long the SHOW SCROLL
   window is.
 + Added "SCROLLFOOTER" which lets you enable or disable the footer bar below
   your SHOW SCROLL window.
 + Added "SCROLLHEADER" which lets you enable or disable a header bar above
   our SHOW SHOW SCROLL window.
 + Added "SCROLLTITLE" which lets you define a title displayed in the SHOW
   SCROLL header, if used.
 + Added "SCROLLCOLOR" which lets you customize the color scheme of your
   SHOW SCROLL header and footer bars and pop-up windows.
 + Added "DO READYESNO" which will display a Yes/No lightbar prompt and set the
   provided string variable to the result.
 + Added "YESNOMAP" which allows you to define the strings of the yes and no
   selection prompts on the following two lines, respectively.
 + Included a silly little WHATSNEW.REF example script. The script's only
   function is to view the WHATSNEW.TXT file included in this archive, but it
   demonstrates several new-ish features, such as using SHOW SCROLL to view
   an external file, customizing SHOW SCROLL, using LIGHTBAR, using CENTER and
   CENTERPAD, and using DO READYESNO and YESNOMAP.
 + As mentioned earlier, there is now a /V command line parameter to enable
   more verbose logging. Generally, REFDoor will only log errors, warnings, and
   SysOp related events. If using verbose logging, you'll see additional
   information messages about loading and exiting, memory usage in memory
   mode, etc. This should improve performance, especially with memory mode on
   slow machines.
 + Modified main parser routine to more efficient handle parsing commands,
   though performance increases probably aren't noticible on anything but
   VERY old/slow machines.

v1.1.0 - Released 01/19/2021
---

 ! Added a range check to parsing string variables to prevent an invalid string
   variable reference from sometimes looping infinitly.
 - Removed some unnecessary variable / control code parsing passes from a
   several commands which might slightly improve performance in some cases.
   These commands were among the first I coded, before variables were parsed
   when read, meaning the separate parsing pass was necessary.
 * I added the following by request to assist with making BBS software specific
   doors. These are really only for specific use cases - DO STRIPALL/STRIPCODE
   should still be the primary command for stripping user input.
 + Added "DO STRIPPCBCOLOR" which strips PCBoard style @ color codes.
 + Added "DO STRIPWCCOLOR" which strips PCBoard style @ color codes.
 + Added "DO STRIPPIPECOLOR" which strips pipe style color codes.
 + Added "DO STRIPSETHCOLOR" which strips SethCode style color codes.
 + Added "DO STRIPWW4COLOR" which strips WWIV style heart color codes.
 + Added "DO STRIPALLCOLOR" which strips all known styles of color codes.
 * Likewise, added a few commands to convert BBS specific color codes to
   REFDoor's "SethCode" style color codes. Note that these only support the
   standard 16 color palette and do not support blinking or ICE colors.
 + Added "DO PCBCOLOR2SETH" to convert PCBoard style @ color codes.
 + Added "DO WCCOLOR2SETH" to convert Wildcat! style @ color codes.
 + Added "DO WW4COLOR2SETH" to convert WWIV style heart color codes.
 + Changed the REF parser version to "11". Starting from this release onward
   the versioning scheme will be based on the major+minor version of REFDoor
   itself. Since this number will always be more than RTReader and LORD 2's
   version of "2" this shouldn't break backwards compatibility, but it will let
   us use the VERSION command for its intended purpose going forward, with the
   assumption that any minor version will include changes/additions to the REF
   language.
 + Added "PAUSEMAP" command. Works exactly the same as MOREMAP but only affects
   the PAUSE command's pause string. This will let you have separate pause and
   more prompts, as long ase PAUSEMAP is defined after MOREMAP.
 + Changes to various SysOp side strings to make the aesthetic a bit more
   fitting for REFDoor rather than previous Darkness styling.
 + Futher changes to the local login to make it look a bit more like the local
   login in post RTReader doors like Planets:TEOS 2.00 and LORD 2.
 ! Fixed a various typos in the documentation.

v1.0.1 - Unreleased
---
 ! Fixed an issue where I was using a Integer instead of a LongInt for filesize
   in the REF picker menu. VP defaults to LongInt sizes for integers, but BP/TP
   uses smaller integer sizes which are too limited for this purpose.
 + Added new multinode sensitive open text file procedures similar to xDoor's
   but with remote output and logging of errors. Updated all text file read
   only and append opens (temporary files, mostly) to use the procedures. Many
   of our procs that were opening text files weren't opening them safely.
 ! Fixed a formatting issue where the time left was being set to a different
   color in Xdoor's updateTime proc than in the statusBar drawing proc. This
   usually manifested itself after the statusbar was redrawn by commands like
   DES and PROGNAME.

v1.0.0 - Released 06/19/2020
---
 Initial release.

Download v1.2.0 of REFDoor!

For the record, I’m planning on continuing work on REFDoor for as long as I continue to make any use of it. I was originally pretty wishy-washy on whether there would be any future work done on the engine, but I’ve finally decided that any work I do to it, even as part of another door, will be rolled into REFDoor proper and released. Stay tuned!

Getting into Amiga – Trouble in Paradise

Not long after the events of my last update I took the next logical step and obtained a set of Workbench 1.3 disks. For those reading who aren’t Amiga users, Workbench is the graphical interface part of AmigaOS and greatly expands the core functionality found within the so-called Kickstart portion of the operating system. While a great many of Amiga’s games and applications are bootable, for anything else you’ll be booting to Workbench. After a bit of a false start resulting from my disk drive being stone dead (which thankfully simply checking and reseating its cables seemed to correct) I was finally able to begin the process of actually learning how to use an Amiga.

Once in Workbench, I started poking around with the various utilities that make up this relatively early version of AmigaOS. As I aimlessly played, I started to encounter all manner of random issues. Sometimes the whole system would lock up or just restart, other times the caps lock light on the keyboard would come on or flash (which, similar to POST beeps on IBM compatible PCs, is one of a few ways Amigas can communicate hardware errors to the user) often with the keyboard totally unresponsive. Then this started happening at boot, before I’d even got past the Kickstart screen, and even when I got past it into Workbench it would happen within a few minutes, often when attempting to access a disk. I was perplexed, since from what I’d read many of the symptoms I’d experienced seemed to be caused by unrelated component failures. I managed to acquire an Amiga Test Kit 1.15 disk to run its numerous simple tests on things like RAM chips and CIA chip timings which all passed, easing my worries somewhat.

My very first Guru Meditation

I wondered if my fancy modern switching power supply was the issue, since I knew that the model of Meanwell I’ve got has very different minimum load requirements from the original Amiga 500 power brick, and if I wasn’t hitting that required minimum, it could be running a little out of spec. It seemed logical to guess that a misbehaving power supply could result in all kinds of odd behavior on an older, simpler computer like the Amiga 500, and of course this could easily explain any power loss and restarts I experienced. Still, after researching it more, and without a multimeter handy while catching it in the act, I couldn’t really confirm that this was the issue. I remained highly suspicious, and while this may be coincidence, I was doing most of my testing without my trapdoor memory expansion installed as I had intended to grab some before and after pictures of Workbench displaying my increased memory for my last post, and noted that when I installed it (and later, other, additional accessories) things seemed to stabilize considerably.

At one point near the peak of my paranoia about these issues, I decided to leave the machine up and running in Workbench with no activity to see how long it would take for it to crash on its own. At first it was happening within 5 or 10 minutes but it gradually seemed to go longer and longer until it stopped entirely. I wondered if perhaps Netsurge, who had given me this machine, hadn’t really used it beyond checking to make sure the Kickstart screen appeared, and that, maybe after what could be decades of not being used, some of its capacitors needed an extended “warm up”. Despite the capacitors in the Amiga 500s not being nearly as problematic as in some other models, at this age them being fully on their way to shuffling off this mortal coil was still a distinct possibility.

At that point I didn’t do anything noteworthy with the machine for a few weeks but upon my next longer session with it I immediately started to have stability issues again. This time they mostly seemed to present themselves when playing with the cables and connectors and/or moving the Amiga around, and mostly seemed to manifest themselves by way of lock ups and total power losses, resets, and odd video output behavior. Because of that correlation, I focused on the power supply once again and observed that even when things seemed to be working perfectly, rocking the supply connector ever so slightly would result in a power loss or a reset. Boys, I think we’ve got ourselves one or more broken solder joints! It’s not surprising that the some of those joints could have finally given out to the stress of 30+ years of pushing in and yanking out the Amiga’s beefy square DIN power connector, and it seems likely that inconsistent power on the rails could indeed result in all of my issues for the same reasons I outlined when talking about the minimum draw issues above, except now my symptoms coinciding with disk drive activity make even more sense. It’s also easy to imagine that the changes in stability I’d observed previously were actually just related to the port’s pins sitting just right in their joints between attempts, and the connector (indeed the whole machine) not being physically moved around too much.

Comparison of Amiga 500 Power Supply Connectors

As a quick aside, my Meanwell power supply conversion is based on an original Commodore Amiga 500 312503-02 power supply. When I plug it in to the Amiga the power connector doesn’t seem to want to sit flush with the outside of the port, though with some additional effort it will go more or less in all the way. I later compared it directly to a slightly older 312503-01 revision Amiga 500 power supply and noted that the connector is actually quite different. The newer 02 model has a fatter housing, with an embossed arrow and the word “TOP” on the top which actually hits up against the Amiga 500’s case somewhat, a longer shield and longer pins, and the “V” shaped cut out on the top of the shield is less distinct and doesn’t extend its entire length. Most significantly, the thinner, shorter 01 connector plugs in fully so that the housing sits completely flush with the outside of the port with ease. It’s quite possible that me attempting to force the longer 02 connector “all the way” in (which, I now know is unnecessary) and then later struggling to yank it free is what damaged the port’s solder joints. 🙁

Opening my Amiga and disassembling it entirely for the first time, which involves unscrewing every single rear connector from the bottom shield so you can see the underside of the motherboard, I confirmed my suspicion. It was fairly difficult to see, but one of the DS-215 connector’s eight pins (pin 1, which is the all important +5V rail!) seemed to have a cracked or broken joint, or, perhaps by the looks of it, maybe even a cold solder joint from a past repair. In any case, it was visibly moving ever so slightly when the connector was wiggled. Time to break out the soldering iron!

The solder joint of doom.

Somehow, despite both a hobbyist and professional computer nerd for 20+ odd years, I’ve always completely sucked at soldering and would typically avoid it in all but the simplest tasks. Still, I figured that simply “reflowing” the existing solder on the broken joints with my busted old cheap soldering iron and perhaps some fresh solder wouldn’t be too far outside of my comfort zone. After talking to a few friends with some degree of expertise in electronics, I was convinced that a vastly superior fix would be to completely desolder the connector and start fresh to guarantee that I had reliable joints that would last me for many years to come, even with my abuse. Scary, but “challenge accepted” I suppose. I mean, this is the age where there are dozens of tutorials on YouTube for even the most obscure tasks, after all.

***Cue an intense training montage of me unboxing and setting up a bunch of brand new soldering equipment and supplies, and practicing soldering and desoldering a variety of small practice kits until my joints were impeccable and I could desolder an entire motherboard in mere minutes. Eye of the fucking tiger!***

While the first part isn’t such an exaggeration, I assure you that the results definitely are. Still, I worked on practicing and improving my soldering skills for a couple of weeks before it was time to put my beloved Amiga 500’s precious motherboard under the iron. As planned, I applied a bit of liquid flux to each joint and used my soldering iron to heat them, then used a spring loaded “solder sucker” and some desoldering wick to remove the solder from each pin entirely. The shield ground pin and the three shield pins gave me some trouble, since, as I now know, they lack thermal pads which causes the heat from a soldering iron to dissipate much more quickly, but the rest went well enough and in the end I was satisfied. I then soldered each pin with a nice new joint, including making sure to be a little generous with the three shield pins, since they seem to provide the most support to the connector port itself. Simple enough!

The outcome? Well, I’m pleased to say that it seems my stability issues are now resolved. While rocking the power connector doesn’t cause any power loss or restarts, at least when fully inserted, I also haven’t observed any stability issues since making the fix. I’ll know more the more I use it of course, but for now I’m happy with the repair.

Time to RTFM

Now, about the whole “learning AmigaOS” thing, I guess I have some reading to do…


1. The infamous “guru meditation” error. This is actually the only one of these I saw during this ordeal, and probably not even related to my problem, but hey, it makes for a dramatic picture all the same!
2. A side by side comparison of the slightly different 312503-02 (top) and 312503-01 (bottom) power connectors.
3. The broken power connector solder joint on the bottom of my motherboard.
4. RTFM time? The original Amiga 500 user’s manual, chock full of basic AmigaOS tips and colorful pictures. Neat.

Getting into Amiga – The Missing Pieces

So, I now had an Amiga 500 of my very own, but I only had the computer itself. I’d need a few more things to be able to turn it on, never mind actually use it.

First and foremost, I’d need a power supply. It’s not too difficult to find original Amiga power bricks on eBay despite them often going for quite a bit more than I personally think they’re worth. Regardless, this is one component where I’d prefer to go with something more modern as I’ve read that these 30 odd year old power supplies fail frequently, and I’ve personally seen enough other power supplies fail in my life to absolutely believe those claims. While a failure would most likely just mean having to deal with the expense and inconvenience of hunting down a replacement, I’d rather not risk frying my Amiga or, worse, burning down my house.

Thankfully there are quite a variety of third party power supplies out there that are made specifically for Amigas. Unfortunately none of them come close to matching the Amiga 500’s design, and there’s just something about that original chunky, beige brick that feels essential to the aesthetic of the whole setup. There’s also the question of the quality of these newer power supplies. Obviously, I wouldn’t be doing myself any favors if I ended up buying something that was just as likely to fail after all. Fortunately I stumbled onto a solution that satisfies both of these concerns.

Amiga 500 Sleeper PSU!

For years Amiga hobbyists have been gutting their dead power bricks and replacing their innards with more modern power supplies, and I stumbled upon someone on eBay who was selling just that. An original Amiga 500 power supply that had been “upgraded” to a Mean Well PT65B. Mean Well is a company that specializes in switching power supplies for a variety of applications, mostly industrial, and several of their models make nearly perfect Amiga power supplies right out of the box. The PT65B should be quieter, cooler, more efficient, and provide me with way more wattage than I’ll ever need regardless of what upgrades I end up throwing its way. I even managed to track down a video of one of the seller’s earlier attempts to build one of these on YouTube. I do have some minor concerns about how well it will handle having too low of a load, but overall I’m quite satisfied with this one.

Next comes the mouse. Amiga mice use the old Atari joystick specification which, despite often using the same DE-9 connector, works entirely differently than serial, so no digging through my PC parts bin for an easy fix, sadly. Again, eBay had a few of the original “tank mouse” style mice that came with the Amiga 500 but there was a surprising amount of competition around those auctions and all of the more reasonably priced ones seemed to disappear right around the time I started searching. While I was determined to have an original Amiga mouse, I wasn’t necessarily all too concerned about which one, and the tank mouse looked like it would be fairly uncomfortable anyway, so I ended up grabbing the cheapest Amiga mouse I could find.

Alfa Data Amiga MegaMouse

You’d think this would be one of the easiest things on my shopping list, but in my haste I did a bit of a half-ass job researching varieties of Amiga mice and from its appearance and seeing what looked like a genuine Commodore stamp on the bottom of the mouse, I’d assumed this was some variation of Amiga 600/1200/4000 mouse. When it arrived in the mail, I opened it up to give it a good clean and had to scratch my head upon seeing no other signs that it was actually a Commodore mouse. In fact, the more I looked into it, the less sure I was about what I’d actually purchased. I did some digging, and it turns out that this is actually Alfa Data “MegaMouse” and not a genuine Amiga mouse at all. A bit of a bummer that I can rectify sometime in the future, but for now I have something that should work at least.

Next up is the 512KB RAM trapdoor expansion card I mentioned in my last update. The A501 was the first party 512KB RAM expansion most people had, but given that they also included a real time clock with a soldered barrel battery that is prone to leaking everywhere, most people opt to replace them with one of the numerous third party RAM expansion cards these days. Mostly because it was conveniently available from Amiga on The Lake, I ended up with this Kipper2K card which adds an additional 512KB of “slow” RAM to an Amiga 500 (or 1MB to an Amiga 500 Plus) and leaves the real time clock optional. Installing it is simply a matter of inserting it into the “trapdoor” expansion port on the bottom of the A500. Simple and cheap.

Installing the Kipper2k 1MB Amiga 500 Plus RAM Expansion

Last but definitely not least, I’d need to worry about how to connect this thing to a monitor. I’d originally mentioned this issue as one of my specific reasons for deciding to not acquire an actual Amiga, and now it was time to face that music.

The Amiga’s horizontal refresh rate is the main problem. I always keep my 486 setup on my desk which includes a 17” CRT monitor, and I’d prefer to use a CRT anyway for authenticity’s sake, but while CRTs typically support a wide range of refresh rates and resolutions, very few go as low as the Amiga’s native 15.75khz horizontal refresh rate. One solution could be to seek out a monitor that does, perhaps an Amiga specific monitor like a Commodore 1084 for instance, but I really don’t need another CRT in my office, and going with a classic model like that would introduce a slew of additional old age concerns to go along with the ones I’ve just avoided with my new power supply.

To use this monitor, or even a newer flat panel monitor for that matter, I’ll need some sort of a “flicker fixer” or “scandoubler” to, well, double that “scan rate” to something my monitor could handle. I knew there were a lot of solutions for connecting Amigas to modern monitors, from internal modifications and open source boards to expensive commercial devices, but what I wasn’t expecting was how unavailable most of them currently are. I have a few models of these things set as “saved searches” on my eBay account that still haven’t shown up once in over a year if that tells you anything. Many of the boards and devices made specifically for Amigas are no longer being produced, and even then, in-depth technical reviews of them usually reveal that few of them are anywhere close to flawless.

Corei64 GBS-8200 Scan Doubler

In the end I went with something of a stopgap solution, opting for decent and cheap, and easy to acquire at that, the infamous GBS-8200. I saw quite a lot of people selling these online, not always disclosing what they were, but ended up going with one sold by Corei64 that comes in a nice little case, pre-wired for the Amiga’s RGB port, and pre-programmed for both NTSC and PAL Amiga video modes. How satisfied I’ll be with this remains to be seen, and I’ll definitely be keeping my eyes open for superior solutions.

So with all of that out of the way, does it work?

First power on of my new Amiga 500!

Yes, it works!

Next time, a couple of big upgrades…


1. My sleeper modern PSU. Looks just like the real thing!
2. The mystery mouse. Can you blame me for thinking it was an actual Amiga mouse?
3. Tossing another 512KB RAM into the trapdoor.
4. My GBS-8200 from Corei64 in all its 3D printed glory.
5. I made it to the Kickstart screen! Don’t mind the weird grey void outside, my camera just hated the lighting here.