The development section contains a mix of materials, all aimed towards helping to maintain and expand the functionality of MARTHA and LLAMA. There are also documents on conversion issues found in going from the mainframe APL version to the PC that may be useful for people attempting conversions to other APL’s. The core functions of MARTHA can be tested using several TEST workspaces available here. There are “modlogs” that document all of the various changes made to the workspaces over time. There is also information on using Microsoft Word with an APL font for documentation, which is how much of the documentation here was created.
Modifying MARTHA: Even after the commercial product was no longer available, and users were limited to MIT Lincoln Laboratory, MARTHA was supplied in “locked” form. This was primarily to eliminate support calls from folks experimenting with MARTHA’s innards. Understanding why requires a little bit of a computer history lesson.
MARTHA was originally written for the IBM mainframe computer when memory was very expensive. APL workspaces had only 32 Kbytes(!) of space, into which all MARTHA functions and variables being used, and all circuit descriptions, user data, and results, had to fit. (Later, in 1975, long before the first ‘IBM PC’, IBM introduced the model 5100, which was the first production personal computer. It had a small built-in CRT display, keyboard, and a tape drive, was available with APL, BASIC, or both, but still had only 64 Kbytes(!) of RAM.) MARTHA was originally written to run in an environment where memory was incredibly precious.
As a consequence, three design decisions were made (that would not be appropriate if MARTHA were being written today). First, the lesser-used MARTHA functions were separated from those deemed to be of more general interest (in the workspace named MARTHA) and placed in library workspaces with names MARTHAE, MARTHAW, etc. Second, none of the MARTHA code contained comments. Third, several ugly programming “tricks” were used to squeeze every last byte of memory out of the programs. These made the code both difficult to follow and dangerous to tinker with.
As an example, a lot of the original MARTHA code has labels on lines that are not the targets of branches, and inserting a line (like a comment) will break the function. Here’s why: if you use a label (like ‘a’) on line [2] in a function, ‘a’ is assigned the value 2 by the interpreter, using a single byte. Ordinarily, ‘2’ would be a 4-byte integer. If you were writing a function that required ‘2’ often, you could save several bytes of memory every time you substituted ‘a’ where you need a ‘2’. However, if a line later gets inserted by an unsuspecting programmer before line [2], ‘a’ will now have the value 3, and everything falls apart.
This is only one example of the tactics required to get MARTHA to run well in 32 kbytes. A number of these issues were dealt with during the conversion from the mainframe code to the PC, but there are undoubtedly others lurking for the unwary. This isn’t meant to discourage anyone who really wants to from working with the MARTHA code. It’s just to make sure they know what to expect. In contrast, the LLAMA workspaces are heavily documented, and are much easier to work with and expand upon.
“Differences” Documents: The original PC version of MARTHA required merging the mainframe version in use at MIT and the one at Lincoln Laboratory. The result was then converted to run on the PC. In the process of doing this, all of the differences and changes were documented so that the final PC version included all of the newer features in both versions. Many workspaces were identical between the two systems, and no ‘diff’ file exists for them. Note: The original unlocked “source code” for the various MARTHA workspaces was in workspaces named Mx5.AWS, where “x” was the last letter suffix of the name of the locked workspace. For example, the code for MARTHA was in M5.AWS, and the code for MARTHAW was in MW5.AWS. Now that the code is being distributed unlocked, this naming convention has been dropped. The following files are contained in the zip file “DIFFS_DOCS.zip” (183 kbytes):
Modification Logs: Any time changes were made to any of the workspaces, they were documented in “modlogs” for future reference. This includes changes made to get the original converted workspaces to function properly, bug fixes, and the updates for the public domain release. All of the current Modlogs are available as PDF’s for easy reading without worrying about installing fonts [Modlog_PDF.zip (391 kbytes)]. Here is a list of the various files:
* not included in regular MARTHA distribution.
If you plan on making any changes to either MARTHA or LLAMA that you would like to see added to the public distribution, you should document them in the same fashion. The editable files are in Microsoft Word format in the file Modlog_MSW.zip (84 kbytes). The APL font required and additional info on moving APL code to Word are described in the section below on documenting APL with Word.
Testing Workspaces: In order to make sure that any changes to MARTHA don’t break anything, a large set of test functions were written that are contained in 3 workspaces. Known good results are compared against the execution of the new code. There are differences in the internal workings of the mainframe and the PC that produced a lot of errors after the initial conversion. These have all been tracked down, but there are a couple of extreme tests that still fail and are difficult to fix. These have been documented in more detail. The operation of the test workspaces is a bit cumbersome at this time, and a lot could be done to streamline things. Because they are not used frequently, this hasn’t been a priority. There are a number of documentation files in MS word format:
The actual test workspaces are TESTM, TESTMA, and TESTMB. There is a new testing workspace that automates a lot of the work required to run the individual tests. It is called RUNTESTS, and the startup message for the workspace is shown below:
Instructions for RUNTESTS Workspace
This workspace automates the MARTHA test operations. For documentation on the tests and the expected results, see the DESCRIBE variable in the workspace ‘TESTM’. The tests are numbered, and each test is run by executing the function ‘RUNTESTx’ in this workspace, where ‘x’ is the desired test number.
Because running the tests requires loading various workspaces, which would overwrite the testing function, a ‘trick’ is used. The ‘RUNTESTx’ function loads the required steps into the keyboard buffer, and then executes them as if they had been typed in. You must reload this workspace to run each different test number.
In order for the test functions to run, there are two background variables that must be set correctly first. They contain the library numbers for MARTHA and the test workspaces TESTM, TESTMA and TESTMB. Check that these match your system before trying to run any of the tests.
The present value of ‘M_LIB_NO’ is 11
The present value of ‘TEST_LIB_NO’ is 5
Valid Test #s Are: 1, 2, 3, 4, 5, 11, 12, 13, 14, 15, 16, 21, 22, 23, 24, 25
All 4 workspaces are included in the zipfile “MARTHATESTS.zip” (286 kbytes).
Documenting APL with MS Word: The key to the long term survival of any computer code is good documentation. Including lots of comments is essential. There is a nice means of providing “on-line” documentation using something called “public comments” that is described in the LLAMA manual that is also a great help. Because of the special APL character set, creating more involved documentation like the LLAMA and MARTHA manuals requires some extra tricks.
STSC/Manugistics/APL2000 has several different Windows “True Type” fonts that can be used in Microsoft Word. APL2000 has graciously given permission to use and distribute those fonts for use with MARTHA and LLAMA. However, the mapping of the characters is different between the different fonts. It also turns out that the character mapping is different depending on whether you save the file as text in APL or try to cut and paste it from a window. Some experiments with APLSE showed that the “APLII.ttf” font maps fairly well between APLSE text files and Word. Code listings and material saved from APLSE into a file can be inserted into a Word document using the APLII font, and most of the APL will be readable. Unfortunately, there are a number of important APL characters and operators that don’t translate properly. The errors produced can be fixed manually by using “Insert – Symbol”, but that gets tedious very quickly.
In order to avoid this, an APL workspace was created that takes text files created in APLSE and re-maps the characters so they come out correctly in Word. The necessary font, procedure, and APL workspace are contained in the zip file ”APLSE_Doc_Fonts.zip” (205 kbytes).