MARTHA and LLAMA - Development Section

MARTHA and LLAMA  Development Section

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 “” (183 kbytes):

‘The Miniature MARTHA Modification and Maintenance Manual’.  Comparison of the code contained in the MARTHA and MARTHAW workspaces between the MIT mainframe code and the PC version.  Summarizes ‘MARTHA DIFFS MIT LL’ and ‘MARTHAW DIFFS MIT LL’.
Detailed list of the differences found between the MIT ‘M5’ code and the ‘M5’ code for the PC derived from the Lincoln Lab mainframe version.  Compiled before any bug fixes were applied.  All further changes detailed in MARTHA MODLOG.
Brief list of the differences found between the MIT ‘MD5’ code and the ‘MD5’ code from the Lincoln Lab mainframe version.  Created before any bug fixes were applied.  All further changes detailed in MARTHAD MODLOG.
Lists all the differences found between the MIT ‘MW5’ code, and the ‘MW5’ code for the PC derived from the Lincoln Lab mainframe version.  This list was compiled before any bug fixes were applied.  All further changes detailed in MARTHAW MODLOG.
Describes key differences found between the IBM mainframe APL and the APL for the PC that weren’t specific to MARTHA.  This could be a handy resource for converting other code.

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 [ (391 kbytes)].  Here is a list of the various files:

For main MARTHA analysis workspace
For MARTHA “development” workspace
For MARTHA “Elements” workspace
For MARTHA Format Functions workspace
For MARTHA Modifiers for response functions workspace
For MARTHA Numerically-Defined-FOF Functions workspace
For MARTHA Response functions workspace
For MARTHA Wiring functions workspace
For MARTHA “Extra functions” workspace
For the on-line summary of MARTHA workspaces and functions
For MARTHA 4-port analysis workspace *
For MARTHA non-linear circuit analysis workspace *
For MARTHA noise analysis workspace *
For main LLAMA workspaces
For LLAMA X-Y plotting workspaces

  * 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 (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:

TESTM Instructions
This is a printout of the DESCRIBE variable in the MARTHA workspaces “TESTM”, “TESTMA”, and ”TESTMB”.  Outlines the procedure and inputs required to test the functionality of MARTHA.
Describes possible issues with running TEST6, which checks how the function NDE deals with low memory conditions.
TEST25 & TEST26 
Contains listings and results of running tests 25 and 26 on the latest version of MARTHA.
Describes changes made to the TESTM workspace as part of mainframe to PC conversion, and updates for public domain release.
Describes changes made to the TESTMA workspace as part of mainframe to PC conversion, and updates for public domain release.
Describes changes made to the TESTMB workspace as part of mainframe to PC conversion, and updates for public domain release.
Lists all of the tests and describes issues found when the conversion was done.

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 “” (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 ”” (205 kbytes).

Home page | Search | Comments and inquiries