ARCHIMEDES 8 -- Merlin 8/Merlin Pro Enhancement Utility by TC Wilson, with docs and some new code by Jerry Kindall Archimedes is Public Domain; that is to say, it's FREE! Doc File last updated on December 7, 1988. INTRODUCTION ============ The first version of Archimedes I uploaded here had a very skimpy doc file. This one's going to be much better, I promise. This new version of Archimedes (which I am calling Archimedes 8 because it was written specifically with 8-bit Apple users in mind) features much better integration with the full screen editor. Archimedes 8 was written for, and tested with, Merlin 8 version 2.58 (ProDOS 8 version). As far as I know this is the most recent version of Merlin 8. Some of the patches in this new version of Archimedes are highly version dependent, so you use Archimedes 8 with older versions of Merlin (such as Merlin Pro, the precursor to Merlin 8) at your own risk. Previous versions of Archimedes included limited support for 65816 opcodes. Archimedes 8, though, does not have the 65816 support. If you use a machine with a 65802 or 65816 microprocessor, you're better off using Merlin 16. It's much faster (and more powerful) than Merlin 8. Archimedes 8, then, is designed specifically to enhance Merlin 8, and the 8-bit full screen editor (ED), on an 8-bit computer. You need a 65C02 to run Archimedes 8. Another thing taken out of this version of Archimedes is the SEE opcode. This opcode was used in previous versions to cause opcodes such as LUP and --^ to be printed on the assembly listing. I ran into bugs that I was unable to solve, so this opcode was removed. If you try to use this opcode, you will not get an error (this means you won't have to take all tthe SEEs out of any source code you may have) but the opcode will have no effect. Historical note: TC Wilson, the original Archimedes programmer, was using Merlin Pro but had a 65816 in his IIc's Z-RAM Ultra II RAM card. So he did a complete disassembly of Merlin to figure out how to add the features he wanted to add. He wrote the program for his own use, to work with Merlin version 2.54. We later discovered that it worked fine with other versions of Merlin Pro (and Merlin 8), including 2.55, 2.57, and 2.58. The current version has been tested only with Merlin 8 2.58. INSTALLATION ============ Installing Archimedes is simple. First, you need to make a disk (or a subdirectory) with the following files: PRODOS - For a bootable disk; optional MERLIN.SYSTEM - The Merlin program itself PARMS - Required by Merlin START - Archimedes startup program ARCHIMEDES - The Archimedes program itself ED - The full screen editor (NOT ED.16) Note: on some Merlin Pro disks, the ED program may be called FS.ED and may be in a subdirectory. The easiest way to get Archimedes up and running in such cases is to copy FS.ED to the main directory and rename it ED. (We have tested Archimedes 8 only with the full screen editor included with Merlin 8, version 2.58. Some versions of Merlin Pro, however, seem to include exactly the same editor, so Archimedes may work with these versions.) Next, you need to tell Merlin to load Archimedes (instead of just the full screen editor) when it is run. How to do this isn't mentioned in the Merlin 8/16 manual, but Merlin has a "startup buffer" much like BASIC.SYSTEM, following the ProDOS standard. Usually this "buffer" contains the filename ED, which makes Merlin automatically load the full screen editor. All we need to do is change this buffer so that it says START instead of ED. This can be done one of two ways. The easiest way is to use ProSel's Block Warden to Follow MERLIN.SYSTEM, then go into edit mode, hit the right arrow key six times, type START when the dialog box comes up, and write that block back to disk. The other way is to get into Applesoft BASIC, then enter the following commands: UNLOCK MERLIN.SYSTEM BLOAD MERLIN.SYSTEM,TSYS,A$2000 CALL -151 2006:05 53 54 41 52 54 3D0G BSAVE MERLIN.SYSTEM,TSYS,A$2000 Once you've done that, you should be all set. When you execute MERLIN.SYSTEM, the messages INSTALLING ED and INSTALLING ARCHIMEDES will now appear on the screen briefly. That's the START program at work. Then Merlin's main menu will appear (with "Archimedes 8" where it usually says "by Glen Bredon"; sorry Glen!). Historical note: The new Merlin 8/16 manual never even mentions that Merlin has a line editor or that a startup buffer is used to load the full screen editor. But it's all still there, just as it was in Merlin Pro. WORKING WITH ARCHIMEDES 8 ========================= When Archimedes is installed, pressing E from the main menu will put you directly into the full screen editor. The same thing will happen when you Load or Append a source file. Pressing OA-Q from the editor will take you back to the main menu. Essentially Archimedes cuts out the middleman, the Merlin editor command line, for maximum convenience. Notice that Archimedes remembers where you were in your source file when you quit to the main menu and return to the editor. You might well wonder how to assemble a file. Just go into the full screen editor and press OA-A for Assemble. An assembly listing will be printed on the screen and the message "Hit a key" will be displayed. When you hit a key, you will go to the main menu where you can save your object code. If an error occurred during assembly, Archimedes will take you not to the main menu but back into the full screen editor with the cursor on the line that caused the error. If a PUT or USE file was being processed at the time, the cursor will be on the line with the PUT or USE instruction. (If you got more than one error during assembly, Archimedes will only remember the first one.) If you abort assembly with Control-C, Archimedes will place you in the full screen editor with the cursor on the line you were editing when you hit OA-A. (Or if you encountered an error but decided to continue assembly, the cursor will go to the line with the error.) Notice that with Archimedes installed, Merlin tells you which line number was being processed when Control-C was pressed. There are a number of things that you can't do from Merlin's full screen editor, such as print an assembly listing on your printer or link relocatable files together. Never fear, Archimedes lets you exit from the full screen editor to the command mode prompt with the OA-C command. From the command mode you can still do all the usual Merlin commands. To return to the full screen edtior, type E (or A if you don't have a source file in memory) and press Return. To go to the main menu from command mode, type Q Return as usual. Note that if you type ASM while in command mode, you will still be in command mode after assembly is completed. Archimedes will not take you to the main menu or to the editor if you are assembling from the command line. It will, however, make a note of the first error (if any) in the source file, so that when you go back to the full screen editor, you will be on that line. Archimedes 8 also changes a few other things in the full screen editor. First, the caps lock (Control-L) "feature" defaults to off. I (and many other people I suspect) prefer not to have my editor force me to type in uppercase. You can turn it back on with Control-L if you like. Also, the annoying bug which allows you to overshoot the top of your source file when scrolling upward with OA-Up-Arrow is gone. When you reach the top of your source file you will stay there! And finally, the insert mode cursor has been changed to an AppleWorks style flashing underscore and the Find mode cursor (Control-F) has been changed to a flashing question mark. You will notice that if you go to the main menu and return to the editor, the cursor type and Control-L status are exactly as you left them. NEW PSUEDO-OPS ============== Archimedes' claim to fame is its enhanced set of pseudo-ops. In no particular order, these are: RRF: Read Random File Syntax: RRF start,length,pathname This allows you to include all or part of a disk file in your object code. The file may be of any type. For example, you might include a shape table from disk in a graphics program (saving you from having to convert it to a long string of HEX psuedo-ops or merge the programs manually after assembly), or you might use it to include a text file for a menu screen, or even to include an entire program as part of another program. (For example, you might have a program that installs another program on a disk. You could assemble the programs separately and include the second program in the installation with an RRF psuedo-op.) If the start and length parameters are both zero, the entire file specified by pathname is included in the assembly. Otherwise the parameters specify a particular portion of the file to be included. You don't need to put quotes around the pathname. This holds true for all Archimedes commands which require a pathname. The numeric parameters can all be expressed by any valid Merlin expression. =RB: Equate to Read Byte Syntax: label =RB byte,pathname This function allows you to get a byte from a file and assign that byte's value to a label. This is QUITE different from including that byte in the object code. You might use this psuedo-op to pull in the number of shapes in a shape table (the first byte of the table) to a label. Then you could use that label as you would any other label, except that its value would be determined at assembly time rather than hard coded into the program. The byte parameter specifies which byte in the file specified by pathname is to be assigned to the label. =RW: Equate to Read Word Syntax: label =RW byte,pathname =RW is much like =RB, except that it reads a word (two bytes) in low/high order from the specified position in the specified file into a label. You might use this to get the offset of the first shape in a shape table. TTL: Page Title Syntax: TTL "title string" In previous versions of Archimedes, this psuedo-op was called SPT, which stood for Set Page Title. It was changed to correspond to Merlin 16's psuedo-op of the same name. Basically TTL allows you to change the page heading during assembly. (As usual with Merlin, you must use the PRTR command from Command Mode, followed by ASM, to get page headings.) Archimedes also automatically includes the filename, the current date, and the current time in the page heading. CAL: CALL a ML Routine Syntax: CAL address This opcode is very dangerous and should only be used if you know what you're doing! Like USR, this opcode calls a user-written machine language routine during assembly. CAL checks to make sure that the first byte of the routine is a CLD instruction to help prevent you from crashing the computer, but from there you're on your own. See the Merlin manual (under the USR psuedo-op) for more information on writing machine-language routines that work with Merlin. PEK: PEEK From Memory Syntax: PEK address This opcode takes the current value (at assembly time) of the specified address and assembles it into the object code. For example, if you had PEK $300 in your source code, and at assembly time, the value of byte $300 was 2C, the PEK instruction would assemble the same as a DFB $2C. The difference is that the value can change from assembly to assembly. =PK: Equate from PEEK Syntax: label =PK address This opcode takes a byte of memory (at assembly time) and assigns it to the specified variable as if with an = psuedo-op. =PK is to PEK as =RB is to RRF. MOP: Merlin Opcode Syntax: MOP "opcd",word MOPD "opcd",byte The MOP psuedo-op is used to define new Merlin opcodes. It is used extensively in the Archimedes source code (you do need Archimedes installed to assemble Archimedes). MOP is not something you're likely to use often. See the source code for further discussion. MLI: ProDOS MLI Call Syntax: MLI call,parmlist The MLI command assembles a JSR $BF00 followed by the call and the address of the parmlist. It is compatible with relocatable files. It's basically like a macro which you might write to do the same thing, except it's built-in. RAMD: RAM Disk Status Syntax: RAMD ON RAMD OFF If you have a sizable RAM disk (besides the standard /RAM volume in s3, d2 which Merlin disconnects), you can use it to dramatically speed assembly by having it automatically copy your PUT and USE files there. On the first pass of assembly, PUT/USE files are automatically copied from disk to RAM. On the second pass of assembly, the files are not read again from disk but instead are read from RAM -- MUCH faster. Then the files are deleted once they are no longer needed. This is an optional feature of Archimedes. To activate this feature, use RAMD ON. To turn it back off (the default), use RAMD OFF. Archimedes assumes your RAM disk's name is /RAM/. See the Customization section if that's not the case. The files that Archimedes puts on your RAM disk are called name.C (C is for Copy) instead of name.S. If you abort assembly when using PUT or USE files those files will be left on the RAM disk. MST: Define MouseText String Syntax: MST "string" This allows you to define strings containing MouseText and inverse characters, mixed in with normal characters. Any characters preceded by a vertical bar character ("|") will appear as MouseText. Any characters surrounded by underscores ("_") will appear in inverse. The rest of the text will appear as normal text. This is designed for strings that will be stored directly to screen memory. If you try to print strings (through COUT) defined this way, it won't work! Also, make sure the alternate character set (or the 80-column card) is on when storing MouseText strings to memory. TYP: Set File Tyle Syntax: TYP type OK, so it's not a new opcode. But with Archimedes installed, you can assemble ANY type of file, not just $00 (NUL), $06 (BIN), and $FF (SYS). ONE MORE FOR THE ROAD ===================== FIX and TEXT editor commands: These two commands used to be extremely slow since they were written in Sweet-16 psuedo-code. Archimedes has completely machine-language FIX and TEXT commands that work at blazing speed. The longest time recorded so far for the new FIX/TEXT commands was 1.5 seconds for a 40K file (on a normal-speed Apple!). CUSTOMIZATION ============= To change the volume name that Archimedes expects for the RAM disk for the PUT and USE directives, change the very last line of the Archimedes source code and re-assemble Archimedes. (Remember, you must have Archimedes installed in memory to assemble Archimedes!) That line currently reads: RamPath str '/RAM/' Be sure that you use single quotes, and that you put a slash BEFORE and AFTER the volume name. Then save the new Archimedes object code on disk. Some Merlin users like to use the EDMAC utility. Archimedes can be made to load EDMAC automatically on startup if you like. First, copy EDMAC to the same directory as MERLIN.SYSTEM. Then load the START source code and search for the string 'do 0'. Change the 0 to a 1. Then assemble and save the START object code. You must also change the ORG statement in ARCHIMEDES to leave room for EDMAC. Search for the first occurrence of 'org'. Change that line from ORG $9600 to ORG $9400. Then re-assemble and save ARCHIMEDES. The next time you boot Merlin, these changes will take effect. RUNNING WITHOUT ARCHIMEDES ========================== Archimedes does take away memory from your source file workarea. For this reason, it's easy to temporarily bypass the loading of Archimedes, and/or the full screen editor, and/or EDMAC (if you are using it). This is done by pressing the ESCAPE key while the various programs are loading, or when you execute MERLIN.SYSTEM. Pressing ESC causes all programs after the program currently being loaded to be ignored. If you press ESC while Merlin is loading from disk, you will not get ED or ARCHIMEDES. If you press ESC while the message "Installing ED" is on the screen, ARCHIMEDES will not be loaded. (If you also have EDMAC loading, the files load in the sequence ED, EDMAC, ARCHIMEDES.) This allows you to free up extra memory for those large programs. If you press S while Merlin is loading from disk, you will get neither ED nor ARCHIMEDES (nor EDMAC); instead, SOURCEROR will be loaded if it's in the same directory as MERLIN.SYSTEM. Sourceror can then be invoked in the usual way from within Merlin (go to the editor command mode, turn off 80-column display, and type USER) without having to load it from disk first. Do NOT use the REMOVE.ED program to remove the editor. It will also remove Archimedes from memory, but it WON'T undo the patches Archimedes made to Merlin, so Merlin will die soon afterward. Instead, save your source, then Quit and re-execute MERLIN.SYSTEM, pressing ESC while MERLIN.SYSTEM is loading. COMMENTS? ========= Archimedes is a public-domain program and therefore you basically use it at your own risk. TC and I have been using Archimedes for quite a while, though, and we haven't had any major problems. In no case can either of us be held responsible for any damages arising from the use of Archimedes, nor can we guarantee that it will work on versions of Merlin 8 or Merlin Pro other than version 2.58. Legal mumbo-jumbo out of the way, if you have comments or questions about Archimedes, you can leave them in my GEnie mailbox (J.KINDALL). TC's not on GEnie, but I'll pass on any questions to him if I can't answer them myself. Enjoy Archimedes 8. TC and I hope it makes your assembly language programming much easier. And as for the much-requested Archimedes 16: yes, it's coming. TC's a busy guy, writing his own BBS system in 65816 code, and he does occasionally have to eat and sleep too. At the time of this writing, Archimedes 16 is finished, and the docs are being written. In addition, TC is adding a few other features to Archimedes 8, and writing up a complete set of Merlin technical documentation (internal entry points, memory variables, and so on, for would-be Merlin hackers.) Just hold your horses.