S-C Macro Assembler Version 2.0 ProDOS (TM) Upgrade S-C Software Corporation 2331 Gus Thomasson,Suite 125 P.O. Box 280300 Dallas, Texas 75228 (214) 324-2050 ProDOS is a trademark of Apple Computer, Inc. --------------------------------------------------------------------- Table of Contents Introduction . . . . . . . . . . . . . . . . . . . . . . 1 Comparison with DOS Version . . . . . . . . . . . . . . . 2 TEXT Command S-C PrODOS Command Interpreter . . . . . . . . . . . . . . 3 Commands Modification to CAT and CATALOG Working with Type SYS Files I/O Hooks GETBUFR and FREBUFR File Buffers Memory Map of Installed System . . . . . . . . . . . . . . 6 New Features in S-C Macro Assembler . . . . . . . . . . . 7 Control-p Command FP Command LOMEM Command HIMEM Command Super HIMEN .INB Directive .AC Directive Full Screen Editor . . . . . . . . . . . . . . . . . . . . 14 Moving Source Files from DOS to ProDOS . . . . . . . . . . 15 80-Column I/O Drivers . . . . . . . . . . . . . . . . . . . 16 NOTICE This manual and the software product it describes are copyrighted by S-C Software Corporation. Neither the manual nor the diskette, nor any part thereof, may be copied by any means without prior written consent (except for the personal use of the registered owner). Copyright (c) 1985 S-C Software Corporation 2331 Gus Thomasson Road, Suite 125 P.O. Box 280300 Dallas, TX 75228 (214) 324-2050 --------------------------------------------------------------------- S-C Macro Assembler Version 2.0 (PrODOS Based) Here is your copy of the latest upgrade to the S-C Macro Assembler. The most important new feature is that this version is based on Apple's new disk operating system, ProDOS. Several other improvements have been made, with the result being an assembler that is even easier to use, and yet faster and more powerful. The disk contains the most recent version of PrODOS, as released by and licensed from Apple Computer. This includes the PrODOS MLI version 1-1-1, BASIC.SYSTEM version 1-1. FILER, and CONVERT. We modified FILER slightly, for simpler operation from the S-C Assembler environment. When you boot the disk, SCASM.SYSTEM will be loaded and installed. SCASM.SYSTEM includes a command interpreter (similar to BASIC.SYSTEM), the S-C Macro Assembler, and a selection of various 80-column I/O drivers. If you are booting in an Apple lie or i/c, that 80-column driver will be automatically installed. If not, a menu will appear offering you a choice of 40-column, Videx Videoterm, Videx Ultraterm, or STB-80 drivers. The source code for each of the drivers is included on the disk, so that you may modify them as you wish or create your own for other 80-column cards. Note that the Videx Videoterm driver is compatible with Applied Engineering's Viewmaster card as well. Other files on the disk include a program for easily LOADing an S-C source file from a DOS 3-3 disk into the ProDOS environment, and various example programs. As is true of all S-C products, the disk is not copy protected in any way. Make a backup copy now, and store the original in a safe place. The FILER program can make such a copy, or you may use the DOS-based COPYA program, or any other copier you have. You may also use FILER to move copies of any individual files from this disk to any other disks you have, including hard disks or RAM disks. We expect you to make as many copies as you wish for your own and to encourage your friends to buy their own copies. - 1 - --------------------------------------------------------------------- Comparison with DOS-based Version 2.0 We have tried to make the transition from DOS to ProDOS as easy as possible. making as few changes in the way you operate the S-C Macro Assembler as we could. As a result, if you are already familiar with the DOS-based version and with the operation of ProDOS, you cam probably begin using our ProDOS version without reading any further. However, we recommend you do read what follows, to pick up the new features. The ProDOS version has a lot less RAM available for source files, due to the massive size of ProDOS itself. However, we have added a new directive (.INB) which allows you to assemble even larger source files than was possible with the DOS version. We added HIMEM and LOMEM commands, to allow you to change the limits on the source and symbol table areas for special requirements. We also added a new directive for producing compressed ASCII strings, a feature which cam reduce the memory requirements of programs having a lot of text messages. Of course most of the differences between the new PrODOS version and previous DOS versions are differences between the two operating systems. If you have used both operating systems with Applesoft, you are already aware of these. SCASM.SYSTEM includes a command interpreter similar in operation to BASIC.SYSTEN. The following commands are supported: -, BLOAD, BRUN, BSAVE, BYE, CAT, CATALOG, CLOSE, CREATE, DELETE, EXEC, IN#, LOAD, LOCK, PR#, PREFIX, RENAME, SAVE, UNLOCK, and VERIFY. In addition, a NOPREFIX command has been added (because I could not remember that "PREFIX/" would set a null prefix). The command interpreter in SCASM.SYSTEM is specially tailored to provide a working environment for the S-C Macro Assembler; as such, it cannot support Applesoft programs. To work with Applesoft programs, you have to load BASIC.SYSTEM. The new "FP" command performs the equivalent of "-BASIC.SYSTEM"; therefore. if your current prefix points to a directory containing BASIC.SYSTEM, you can go to Applesoft by merely typing "FP". TEXT Command: We did have to change the syntax of one option of the TEXT command. In the DOS version "TEXT/ filename" writes the source program to disk as a text file, prefixing each line with the current tab character. To ProDOS "TEXT/ pathname" looks like a volume specifier, and most likely returns a PATH NOT FOUND error. Therefore, the ProDOS version uses "TEXT% pathname" for this option. - 2 - --------------------------------------------------------------------- The S-C ProDOS Command Interpreter Our command interpreter is similar to BASIC.SYSTEM, and indeed was derived from it. We started by deleting all sections of code which were only in BASIC.SYSTEM to support Applesoft, and then completely re-wrote the rest. The result is still general enough that you may find it able to support your own projects. SCASM.SYSTEM does not support Applesoft. Assuming the appropriate prefix is set, you can switch back to Applesoft by typing -BASIC.SYSTEM or FP. Commands: The commands supported by our command interpreter are a subset of the BASIC.SYSTEM commands: -, BLOAD, BRUN, BSAVE, BYE, CAT, CATALOG, CLOSE, CREATE, DELETE, EXEC, IN#, LOAD, LOCK, PR#, PREFIX, RENAME, SAVE, UNLOCK, and VERIFY. We also added the NOPREFIX command. All of these commands can be typed at the command level. Unlike BASIC.SYSTEM, our command interpreter has no ability to ge commands directly from keyboard input. The S-C Macro Assembler passes commands it does not recognize on to the command interpreter by calling it through the global page hooks. The "command passing" procedure is the same as that described in the BASIC.SYSTEM Reference Manual. The OPEN and WRITE commands are also included, but they are only for the internal use of the S-C Macro Assembler in support of the TEXT command and .TF directive. Our OPEN command (and hence TEXT command and .TF directive) does not support the L or T parameters. Our WRITE command (and hence TEXT command) does not support the B, F, or R parameters. The following BASIC.SYSTEM commands are not included in our command interpreter: READ, POSITION, CHAIN, FRE, NOMON, STORE, APPEND, RESTORE, FLUSH, and RUN. The LOAD and SAVE commands are designed to work with S-C source code files. BASIC.SYSTEM works with Applesoft files, type BAS ($FC). S-C source code files are type $FA, which BASIC.SYSTEM calls type INT. In our command interpreter, they are called type "S-C". Our CAT and CATALOG commands will show type S-C for these files, whereas BASIC.SYSTEM will catalog them as type INT. Our version of FILER has been modified to call them type S-C. The CONVERT program and the Apple //c System Utilities disk will convert S-C source code files from DOS 3.3 type I files to ProDOS type INT (S-C) files. You may use the "S-C" file type code in commands with the T parameter. For example, "CATALOG,TS-C" will list only files that are type S-C. Sometimes it is useful to be able to set a null prefix. I could not remember to type "PREFIX/" for that purpose, so I added the NOPREFIX command. - 3 - --------------------------------------------------------------------- Modification to CAT and CATALOG: During a CAT or CATALOG, typing or will abort the listing of files. The "BLOCKS" line will still be listed. You can also pause and restart the catalog listing by pressing any other key. Once paused, you can list one more line at a time by pressing two keys simultaneously. I rearranged the second and third columns of information in the CAT and CATALOG listings: the TYPE column is now listed ahead of the filename. This allows you to move the cursor up to a filename, type a command such as LOAD or DELETE or RENAME, and scan over the name with the right arrow key. If the command is "LOAD", you can type , the letters "I" and/or "M" to move the cursor to the line with the filename, and then "L" to automatically generate the LOAD command. (Just as in the DOS version.) Working with Type SYS Files: BASIC.SYSTEM had some arbitrary restrictons built in to its handling of SYS files. In our command interpreter you may BLOAD and BSAVE type "SYS" files as long as you specify the type ("TSYS") and include the loading address. Of course you must also include the length or end address with BSAVE. The file may be BLOADed anywhere it fits, not just at $2000. You may also BSAVE it from anywhere, but when you use the command to execute it the file will be positioned at $2000. Another restriction we removed had to do with using the BSAVE command. BASIC.SYSTEM did not allow BSAVEing to a file that did not already exist if the T parameter was specified. Without the T parameter, BSAVE will gladly create a new file; with T, it gives an error message. Our command interpreter does allow you to create a new file with a BSAVE, even if T is specified. One reason for removing the restrictions of BASIC.SYSTEM was difficulties we had with the FILER program. You cannot successfully enter the standard Apple FILER from S-C Macro by typing "-FILER", because standard FILER is a SYS file and too large to fit between $2~00 and $73FF. Our special version of FILER is on the release disk, which you CAN run with "-FILER". This is a type "BIN" file, and loads at $1000 before repositioning itself. This modified version also calls type $FA files "S-C" like SCASM.SYSTEM does. I/O Hooks: Our command interpreter implements the PR# and IN# commands in the sane way as BASIC.SYSTEM. The same I/O hook locations are supported in the $BE00 Global Page. On the other hand, SCASM.SYSTEM does not switch the I/O hooks back and forth all the time. In fact, unlike DOS or - 4 - --------------------------------------------------------------------- BASIC.SYSTEM, the command interpreter is never connected to the input or output hooks. S-C Macro feeds commands which it does not recognize to the command interpreter via the page 2 buffer. GETBUFR and FREBUFR: Under BASIC.SYSTEM, if you want to reserve some memory for private purposes, you call the GETBUFR subroutine. When you want to release it you call FREBUFR. The space allocated is located below BASIC.SYSTEM, and above the disk buffers. The entry points to GETBUFR and FREBUFR are in the $BE00 global page. Our command interpreter does not have any GETBUFR or FREBUFR subroutines. Instead, we added a HIMEM command to the S-C Macro Assembler. By lowering HIMEM you cam make space for your own routines. File Buffers: BASIC.SYSTEM has one fixed-location file buffer, and dynamically allocates additional file buffers, grabbing 1024 byte chunks for each open file. A large amount of overhead is associated with this process, due to the requirement of shuffling the string storage space up and down each time a file is opened or closed. Our command interpreter has three fixed-location file buffers. This is the amount needed to support the maximum possible file activity, allowing simultaneous EXEC, include, and target files. BASIC.SYSTEM allows more than one file to be OPEN at a time (via the OPEN command), but there was no need for this in the S-C Macro Assembler. Therefore only one file at a time may be OPENed. - 5 - --------------------------------------------------------------------- Memory Map of Installed System ProDOS MLI has not been changed in any way. This is installed by the SYS file named PRODOS when you boot a ProDOS disk. It occupies the entire $D000-$FFFF area, including both banks of $D000-DFFF. In addition, there is a global page at $BF00-BFFF used for communication with command interpreters. Our command interpreter is installed from $AA00 through $BEFF. The global page at $BE00-BEFF is almost the same as that of BASIC.SYSTEM. The assembler is installed from $8000 through $A9FF. The last two pages ($A800-A9FF) are reserved for the screen I/O driver. There are three permanently assigned file buffers at $7400, $7800, and $7C00. The $7400 buffer is used only for the EXEC command. The $7800 buffer is used only for TEXT and .TF files. (This is the buffer used by the OPEN command.) The $7C00 command is used for all other operations ( LOAD, SAVE, CATALOG, etc.). If you have more than 64K RAM, the additional memory may be used as a RAM disk. S-C Macro does not interfere with or use any of the additional memory. HIMEM normally is set to $7400, and LOMEM at $1000. Source code files are loaded just below HIMEM. During assembly of a program (the ASM command), the symbol table begins at LOMEM and grows toward the source program. The HIMEM command allows you to move HIMEM to any page boundary at least one page higher than LOMEM, and up to $7400. The LOMEM command allows you to move LOMEM to any page boundary as low as $0800, and as high as one page below HIMEM. In the DOS 3.3 version the HIMEM and LOMEM pointers were kept in page zero locations $4C-4D and $CA-CB respectively. In the ProDOS version HIMEM is in $73-74, and LOMEM is in $67-68. Most other page zero usage is the same in the two versions. Locations $00-1F are not used by either version, but are reserved for your own use. - 6 - --------------------------------------------------------------------- New Features in the S-C Macro Assembler Three new commands and two new directives have been added to the ProDOS version of the S-C Macro Assembler Version 2.0, which are not include in the DOS version. We have also included a new "keyboard macro" for the PREFIX command to make life with PrODOS a little easier. Control-P Command: If you type a control-P character at the beginning of a line, the word "PREFIX" will be spelled out for you. This is a "keyboard macro", and is analogous our use of control-C to generate the word "CATALOG" and control-E to generate the word "EDIT". After the control-P you may type the RETURN key to see what the current prefix is; type a "/" and RETURN to set a mull prefix; or type any valid pathname to set a new prefix. FP Command: The FP command issues a "-BASIC.SYSTEM" command to the ProDOS command interpreter. It is simply shorthand for that command. If the current prefix points to a directory that includes the BASIC.SYSTEM file, then the FP command will switch you over to Applesoft. If not, it will merely give the "PATH NOT FOUND" error message. LOMEM Command: The assembler builds its symbol table starting the current LOMEM address and building up toward the beginning of the source code. LOMEM is initially set to $1000. You may change the LOMEM value by typing LOMEM followed by an address. The address must be on a page boundary, no less than $0800, and no larger than one page below the current HIMEM value. LOMEM $0800 LOMEM 16384 LOMEM $1234 (invalid, not on page boundary) LOMEM $0700 (invalid, too low) LOMEM $8000 (invalid, too high) There are actually two symbol tables: the main one which grows upward from LOMEM, and one for macro private labels which grows downward from LOMEM. If you set LOMEM at $0800 there will be no room for any macro private labels. (Macro private labels are the ones which begin with a colon.) Why would you ever want to move LOMEM? Perhaps you have a source program which is just a little too large to fit between $1000 and $7400. Lowering LOMEM may make enough room. Or perhaps you are assembling directly to RAM and the object code needs extra room. Raising LOMEM might make enough extra room for the object program. Or perhaps you just want to experiment. - 7 - --------------------------------------------------------------------- LOMEM changes the byte at $803C, which is the starting page for the symbol table, and then re-initializes the assembler. This means that amy source program in RAM at the time will be deleted. Be sure you change LOMEM before you LOAD your source program1 or SAVE your source program before you change LOMEM. If you are curious as to what the current value of LOMEM is, you can use the MEN command. It will display the current start and end of the symbol table, and the current start and end of ~ your source program. HIMEM Command: Your source program resides in RAM below HIMEM. HIMEM is set during initialization by picking up the page number from $BEFB, inside the command interpreter~B global page. HIMEM changes the byte at $BEFB, which is the page for the HIMEM value, and then re-initializes the assembler. This means that any source program in RAM at the time will be deleted. Be sure you change HIMEM before you LOAD your source program, or SAVE your source program before you change HIMEM. The value you specify with the HIMEM command must be on a page boundary, no higher than $7400, and no lower than one page above the current LOMEM. HIMEM $7000 HIMEM $7400 HIMEM $8000 (invalid, too high) HIMEM $7324 (invalid, not on a page boundary) One reason for lowering HIMEM would be to make room for a protected region of memory to place an object program. Perhaps you want to add some additional features to the assembler, and they could be loaded into that area. If you are curious as to what the current value of HIMEM is, you can use the MEM command. It will display the current start and end of the symbol table, and the current start and end of your source program. Super HIMEM: It is actually possible to raise HIMEM even higher that $7400, but not with the HIMEM command. You might want to do so to work on a super large file, just long enough to split it into two shorter files. The buffer which occupies the space from $7400 through $77FF is only used by the EXEC command; if you are not planning to use the EXEC command for a while, you could safely raise HIMEM to $7800. The buffer from $7800 through $7BFF is only used by TEXT and .TF; if you are not going to use these, you could lift HIMEM as high as $7C00. (The DOS.LOAD program also uses these two buffer areas, so it would conflict with such a high HIMEM.) - 8 - --------------------------------------------------------------------- The procedure for raising HIMEM above $7400 is simple. All you have to do is change the value at $BEFB using a monitor command, and then type NEW :$BEFB:78 :NEW C'est possible, mais c'est dangereux. .INB Directive: The .INB directive is similar to the .IN directive. Both are used to include additional source files during assembly. Following the .IN or .INB, separated by at least one space, should be a pathname. 1010 .IN SRC/PART.l 1020 .INB SRC/PART.2 1030 .INB PART.3,S6,D2 The source program which contains the .IN or .INB directives is called the "root" program. During assembly the root program is temporarily "hidden", and source is read into memory from the included file. The difference between .IN and.INB is this: .IN loads the entire included file into RAM, and .INB only reads in one disk block (512 bytes) at a time. If you are assembling large programs, you may need to break the source code into two or more separate files. A small root program, containing little else but .IN or .INB directives, links the source files together during assembly. For example, the three lines 1010-1030 above would assemble the three files PART.l, PART.2, and PART.3 as one large program During assembly, all .IN, .INB, and .TF limes are listed during both passes. They are listed even if the .LIST OFF option has been selected. This allows you to monitor the progress of the assembly. The .INB directive is a little slower than the .IN directive, because the processing between disk accesses slows down the reading of the source files. The speed penalty is not large, perhaps about l0%. What you gain with .INB is the ability to assemble files as large as you can edit, files that use all the space between LOMEM and HIMEM. With .IN there would not be room in memory during assembly for these large files, but with .INB blocking the file it will all fit. If you abort an assembly by typing the RETURN key, and if the assembly was currently inside an included file, .IN and .INB again operate differently. .IN will leave you inside the included file, and the prompt symbol will become "I:". You can modify the currently included file, save it, and type RESTORE to get back to the root program. Or simply type ASM to restart the assembly (ASM does a RESTORE operation before beginning an - 9 - --------------------------------------------------------------------- assembly). If you abort inside a file included with the .INB directive the RESTORE operation is automatically performed: you wind up immediately back in the root program. You may like to experiment with the blocking factor that .INB uses. Normally the file is read in one block at a time, but you can adjust it up to nine blocks at a time. Simply type a digit after the .INB to indicate how many blocks to read a time: 1040 .INB3 PART.3 reads 3 blocks at a time 1050 .INB2 PART.7 reads 2 blocks at a time If you are running an assembly from floppy disks, using too large a blocking number can lead to slower assemblies. If the disk has time to stop between reading sections of a file, it will waste more time trying to get it spinning again. Our experiments show .INB4 to be about optimum. .AC Directive: The .AC directive allows you to assemble a large amount of text in a compressed format. "AC" stands for "Ascii Compressed". It is a powerful tool, but not one for the weak at heart. It takes a lot of planning and programming to make effective use of the .AC directive, but it can be worth the trouble when you have many messages and a strong need to reduce memory usage. The .AS and .AT directives also assemble ASCII strings, using one byte for each character in the string. The .AC directive can use as little as four bits per character, and usually averages about five bits per character The technique uses a set of three encoding tables, each containing 15 characters. The first table contains the 15 characters which occur the most frequently in the body of text to be encoded. Each character found in the table will be encoded as a single nybble (four bits), with a value from 1 through $F. If a character to be encoded is not found in the first table, a nybble NON will be assembled. The second table contains the next most frequent set of 15 characters. If a character is found in the table, it will be encoded by a zero nybble (from the first table) plus another nybble in the range from 1 through $F. If there are no more than 30 different characters used in all of your messages, this may be all the tables you need. If there are more than 30 characters, you will need a third table. Characters not found in either the first or second table will assemble two "zero nybbles", one for the first table and the second for the second table. The third table contains 15 more characters, less frequently found in your messages than those found in the first and second tables. If a character is found in the third table, it will be assembled as two zero nybbles plus another nybble in the range from 1 to $F. - 10 - --------------------------------------------------------------------- If a character to be encoded is not in any of the three tables, it will take five nybbles to assemble. There will be three zero nybbles, followed by the actual 8-bit Ascii code of the character. In actual practice, it usually turns out that three tables are sufficient. The error messages in the S-C Macro Assembler are encoded with three tables, and there are unused character positions in the third table. The same goes for the error messages in our ProDOS command interpreter. The error messages in BASIC.SYSTEM are encoded in a similar fashion, and a very good description of the technique used can be found in Sandy Mossberg's article "ProDOS Cryptography", Nibble Magazine, March, 1985, pages 72-81. Our technique compresses the same messages found in BASIC.SYSTEM even more tightly than Apple's technique; furthermore, our messages can be selectively printed with a smaller decoding routine. Our technique also gives slightly more flexiblility, and lends itself to many creative uses. As an example of the technique, suppose the three tables are as follows: Table 1 2 3 4 5 6 7 8 9 A B C D E F ----- ----------------------------- 1 A C D E F I L N O P R S T ~ 2 B G H K M U V W X Y / ( ) : . 3 J Q Z - 5 6 7 8 9 0 1 2 3 4 & With these tables, the message "SYNTAX ERROR%" would be encoded as: S Y N T A X E R R O R % C 0A 08 D 1 09 E 4 B B 9 B F or C0 A0 8D 10 9E 4B B9 BF We compressed the original 13 byte message into only 8 bytes. The character "%" is used this particular case to mean "end of message". You are free to choose any character for that purpose. The tables above happen to be very similar to the actual tables used in compressing the error messages in our command interpreter. The total number of characters in those messages is 388, and they compress to 451 nybbles, or 226 bytes. The average number of bits per character is thus 4.66. It obviously takes a longer program to find and print a message that has been compressed than it does to print one that is stored in plain ASCII. However, if you have a lot of text, it does pay off. The program used by our command interpreter takes only 130 bytes, including all bells and whistles: 130+226 = 356, so the total is still less than the original messages alone! And the un-compressed messages would still require a subroutine on top of the 388 bytes. If we had more messages, the savings could be even more dramatic. - 11 - --------------------------------------------------------------------- Using the AC directive requires some preliminary work. You first need to reduce all your messages to printing characters. If there are any control characters in your messages, substitute a printing character not otherwise used in your text. For example, we substituted the "%" character for end-of-message above. Next we manually counted the frequency of each and every character used. In the command interpreter's messages we found 69 E's, 27 O's, on down to one X and one W. Manually counting is no fun, so we included a program onthe S-C Macro Assembler disk called AC.FREQUENCY. This program will analyze a set of messages and print out the frequency results. It will even print out the table set-up directives for you to insert into your program. The AC.FREQUENCY program analyzes whatever messages you assemble between the two labels MESSAGES and END.MESSAGES. The copy on our disk contains the messages from our command interpreter. After looking it over, delete our messages and put in your own. Assemble the program, and run it with "MGO 2048". All the text of your messages will be printed first, then the frequency table (in hex dump format), then the three set-up lines for the .AC directive, and finally the frequency table in descending order. There are five different forms of the .AC directive. One is used to initialize the nybble generator. three to set up the three encoding tables, and one declares what text will be compressed. .AC 0 Initializes the nybble generator .AC 1dstringd Sets up the first table .AC 2dstringd Sets up the second table .AC 3dstringd Sets up the third table .AC dstringd A string to be compressed. For example, to set up the three tables given above, and encode a few messages, you would use the following: .AC 0 .AC 1"ACDEFILNOPRST %" 15 chars each .AC 2"BGHKMUVWXY/():." .AC 3"JQZ-5678901234&" .AC "SYNTAX ERROR%" .AC "WRITE PROTECTED%" .AC "END OF DATA%" .AC "/" flush buffer After the last message, it is possible for the last nybble to be waiting in the nybble generator's buffer. To flush out that last nybble. if it is there, write one final AC line with a d single character string. If there was a buffered nybble, it will pop out. If not, nothing will be generated at all. For the messages in our command interpreter, the second most frequent character was the space. In some messages there were strings of spaces up to nine spaces long. It turned out we - 12 - --------------------------------------------------------------------- were able to save additional memory by encoding long strings of blanks with three-nybble codes, by using entries in the third table. Then we use single characters to indicate the multiple blank strings. For example, the "BLOCKS FREE" message at the end of a catalog is generated by the following line: AC "BLOCKS FREE:0BLOCKS USED:8TOTAL BLOCKS:6%" The character "0" is decoded by our message printer as ten blanks, "6" as six blanks, and "8" as eight blanks. By creative planning and some experimentation you can come up with all sorts of memory saving tricks using the AC directive and appropriate decoding message printers. The "decoding message printer" subroutine for compressed messages can take on various forms, depending on the clever tricks you have built into your coding scheme. My printers usually break down into three parts: a message finder, a decoder-printer, and a nybble-picker. The message finder takes advantage of the fact that each message ends with a unique end-of-message character. Given a message number to locate, it simply scans through the compressed message text counting end-of-message characters until it finds the end of the message before the one we want. To make this work I put a null message at the beginning (no text, just an e-o-m). The scanning is done by repeatedly calling the nybble-picker. Here is a sample nybble-picker I call it with the carry status clear to get the left nybble, or carry set to get the right nybble. The X-register holds the index of the current byte. The code below also assumes all of the messages together occupy no more than 256 bytes. Other nybble-pickers could allow for larger blocks of compressed text. GET.NEXT.NYBBLE LDA MESSAGES,X BCS .1 2ND NYBBLE LSR 1ST NYBBLE LSR LSR LSR TAY SEC RTS .1 INX AND #$0F TAY CLC RTS Note that the nybble-picker automatically toggles the left-right status1 and increments the index. It also returns the nybble in both the A-register and the Y-register The Y-register is the important one, because it will be used to index into one of the three decoding tables. - 13 - --------------------------------------------------------------------- The decoding tables are quite similar to the encoding tables used by the .AC directive. The characters will most often be the same in both. However, they will be assembled along with your message decoder-printer. Here are the decoding tables used by our command interpreter: TABLE1 .HS 00 .AS -"ACDEFILNOPRST " .HS 8D TABLE2 .HS 00 .AS -"BGHKMUVWXY/() :." TABLE3 .HS 00 .AS -"JQZ-" .HS 05.06.07.08.09.0A.0B.0C.0E.0F.10 There are some coding tricks involved in the setup of the decoding tables above. I used negative ASCII codes for all the actual letters and punctuation symbols in the tables; a zero code for a flag to move to the next table; and positive, non-zero codes for blank counts. The rest of the source code of the message printer for our command interpreter is included on the S-C Macro Assembler disk. We also included the code for the message printer used in the assembler itself, which has some significant differences. These are both in the file MSG.PRINTERS, for your A inspection and study. Full Screen Editor We have modified and simplified the Laumer Research Full Screen Editor to operate with the ProDOS Version of the S-C Macro Assembler. The ProDOS Full Screen Editor files are now included on the back of the Editor disk. Since ProDOS uses the entire upper 16K of RAM, the Full Screen Editor can no longer use the alternate bank at $D000. This new version runs below the assembler's disk buffers, from $6500-73FF. The new .INB assembler directive overcomes the loss of this much source code storage. Owners of the Full Screen Editor can return their original diskettes to S-C Software for revision. For a $5 fee we will add the ProDOS version to the back of the disk, update the DOS version to include the latest revisions, and send you a supplement to the documentation. - 14 - --------------------------------------------------------------------- Moving Source Files from DOS to ProDOS S-C Macro Assembler stores source files as though they are Integer BASIC programs. Of course they really have nothing to do with Integer BASIC, but it's convenient in working with DOS and PrODOS to pretend that they do. Under DOS, source files are stored as type I files; under ProDOS, as type INT. Our command interpreter and modified FILER rename the INT type "S-C". CONVERT, a standard Apple PrODOS utility, can be used to move files from DOS to ProDOS or vice versa. The Apple //c System Utilities program can do the same job. They both can successfully move S-C source files in either direction. However, there are some severe bugs in CONVERT which continually bite me. For one, CONVERT does not know how to handle a DOS disk which has "funny" file names, such as are commonly used to divide catalogs into labelled sections. I wanted a faster and surer way to move source files from DOS to ProDOS, so I wrote a program called DOS.LOAD. This file is on the S-C Macro Assembler disk. The source code for the program is also on the disk, as S.DOS.LOAD. When you -DOS.LOAD or BRUN DOS.LOAD the program asks for a slot and drive number. Put the DOS disk containing the source files you want to access into any drive, and type the slot number (1-7) and the drive number (1 or 2). The DOS.LOAD program will then display a menu of the type I files on the disk, and wait for you to select one of the files. If there are more than 20 files, you can page through them by tapping the space bar. You can also abort the operation by typing the ESCAPE or RETURN keys. If you select a file by typing the menu letter, that file will be loaded into the assembler's edit area. You just loaded a source file from a DOS disk, and yet you are still in the ProDOS assembler! Now you can SAVE it directly onto a PrODOS disk, or whatever you want. DOS.LOAD loads inside the EXEC file buffer, which means that of course you should not try to BRUN it from inside an EXEC file. It also means that if you do not use the EXEC command in the meantime, that DOS.LOAD stays in memory ready to use again and again. You can keep loading DOS-based source files by re-entering DOS.LOAD with the $7400G command. A full description of the internals of the DOS.LOAD program has been published in the July 1985 issue of the "Apple Assembly Line". There is no reason why this program could not be extended to allow transfer of other file types, and we encourage you to try your hand at this challenging project. - 15 - --------------------------------------------------------------------- 80-Column I/O Drivers SCASM.SYSTEM includes a 40-column driver which should be compatible with any Apple II system, and four different 80-column drivers. The source code for all five drivers is included on the disk. When you boot the disk, or when you type "-SCASM.SYSTEM", the installation program first checks the fourth byte of the SCASM.SYSTEM file (at $2003). If that byte is non-zero, it selects one of the four 80-column drivers. On the release disk that byte is zero, but you may modify it for your own use. When the driver selection byte is zero, the installer checks to see if the Apple is a //e or //c ($FBB3 contains $06). If so, the 40/80-column driver for those two machines is automatically installed. If not, a four-choice menu allows you to manually select the 40-column, Videx Videoterm, Videx Ultraterm, or STB-80 driver. If you are using an Apple //e or //c and wish to override the automatic loading of the 40/80 driver, you can do so by changing the driver selection byte. Or, if you wish to bypass the four-line menu and directly install the one of the other drivers, you again do so by changing the driver selection byte. the hexadecimal values of the driver selection byte to force installation of particular drivers are these: $01 -- Standard 40-column Driver $02 -- Videx Videoterm $03 -- Videx Ultraterm $04 -- STB-80 Remember that a value of $00 will force the 40/80 driver in a //e or //c, or the menu in other computers. Values other than 00-04 will result in disaster. Here is the procedure for changing the driver selection byte: :BLOAD SCASM.SYSTEM,TSYS,A$2000 :$2003:0x (x 0 to 4) :BSAVE SCASM.SYSTEM,TSYS,A$2000,L$4600 SCASM.SYSTEM is a type SYS file, designed to be booted or executed with the "-" command. It may also be BLOADed and BSAVEd as shown above, when you are operating within the environment of the S-C Macro Assembler. The layout within SCASM.SYSTEM is like this: $2000-21FF Installation code $2200-4AFF Assembler with 40-col driver $4B00-5FFF Command Interpreter $6000-60FF 40/80 driver for //e & //c $6100-61FF STB-80 driver $6200-63FF Videx Videoterm Driver $6400-65FF Videx Ultraterm Driver - 16 - --------------------------------------------------------------------- The driver source files include the appropriate .OR (origin), .TF (target file), and .PH (phase) directives to produce a BLOADable object file which will correctly position itself in the SCASM.SYSTEM image. Thus if you make some changes to one of the drivers you can assemble it, BLOAD SCASM.SYSTEM as above. BLOAD the driver object file, and then PSAVE SCASM.SYSTEM as above. If you have a different kind of 80-column card, you can probably modify one of the existing drivers to work with your card. Usually the Videx Videoterm driver is the most suitable for this kind of modification, as most other board makers have claimed to be compatible with the Videoterm. (Note that we have tested this driver with the Applied Engineering Viewmaster and found it to be fully compatible already.) The space allocated for drivers is 512 bytes long, which should be adequate for any type of 80-column card. The STB80 and 40/80 drivers fit within one page, so only one page is allocated within the SCASM.SYSTEM image for them. The two Videx drivers are longer, so two pages each are allocated for them. Slip your own modifed driver into the space that fits best. If you have further questions about 80-column drivers not answered above or in the source code of the various drivers1 please call us at (214) 324-2050. Notes on Individual Drivers 1 40/80 //e & //c Driver. This driver boots up in 40-column mode. You can enter 80-column mode by typing the PR#3 command. Pressing ctrl-RESET takes you back to 40-column mode. With the original //e firmware1 some of the escape key functions are usurped. Therefore I was unable to implement esc-L and esc-S on these machines. The same function can be performed on these machines by holding down the open-apple key and typing L or S. To activate a printer. type PR#1 (or PR# with whatever slot your printer card is in). When you are through printing, you can disconnect the printer in various ways. Ctrl-RESET always does it, and also places you in 40-column mode. If you were in 40-column mode, type PR#0 to disconnect the printer and return to 40-column mode. If you were in 80-column mode, type PR#3 to disconnect the printer and return to 80-column mode. Depending on the particular printer interface card you have, the screen output may or may not be suppressed when your printer is activated. If you see no screen output, don't worry about it; just keep typing, and all your output will be printed. The screen output will return when you disconnect the printer. - 17 - --------------------------------------------------------------------- 2. STB-80 Driver; The STB-80 was one of the best 80-column cards on the market, but it's unfortunately no longer in production. STB Systems now concentrates all their efforts on the IBM marketplace. They sold many thousands, and I have one, so we have a driver for it. The STB-80 driver comes up in 80-column mode, and there is no way to change to 40-columns while in the assembler environment. To activate a printer, use the PR#slot command. To disconnect the printer, use ctrl-RESET. 3. Videx Videoterm Driver: Our Videoterm driver is intended to be independent of the firmware level. Several functions are implemented by direct access to the hardware on the Videoterm card. The Videoterm driver comes up in 80-column mode, and there is no way within the assembler environment to change to 40-column display. To activate a printer, use the PR#slot command. To disconnect the printer, use ctrl-RESET. 4. Videx Ultraterm Driver: Our Ultraterm driver is intended to be independent of the firmware level. Several functions are implemented by direct access to the hardware on the Ultraterm card. The Ultraterm card has many diplay modes, which is probably why you bought it. Our driver leaves it in whatever mode it was in before you started up the assembler. You can switch modes by using our "-command followed by the appropriate control codes. For example, to set 80x48 mode type a quotation mark, ctrl-O. ctrl-V, and the digit 6. When you press RETURN the ctrl-V6 command will be sent to the Ultraterm, changing the display to 80x48. Of course, you may also add code to the driver initialization to set your favorite mode at startup time. If you do change the number of lines on the screen display to a value other than 24, you will also want to make a small patch in the assembler. The EDIT command always VTABS to the bottom of the screen to display the line being edited. Unfortunately, it always believes the bottom is line 23. If you have a 32- or 48-line display, you will want to change the value at $803A to $1F (31) or $2F (47); for normal 24-line displays, the value is $17. To make a permanent change, patch the location $223A in the SCASM.SYSTEM image. To activate a printer, use the PR#slot command. To disconnect the printer, use ctrl-RESET. - 18 - ---------------------------------------------------------------------