100 ; REM PROG NAME IS 'ASMDOC' 2 JUL '87
110 ;
120 CLS:DIM Z$1:Z$=HEX(0C):N%=57:GOSUB FRAME:N%=61:GOSUB FRAME
130 N%=59:GOSUB FRAME:N%=59:GOSUB FRAME:N%=58:GOSUB FRAME:N%=59:GOSUB FRAME
140 N%=60:GOSUB FRAME:N%=60:GOSUB FRAME:N%=59:GOSUB FRAME:END
150 RESTORE 533:N%=60:GOSUB FRAME:END
160 ;
170  "FRAME"
180 SELECT PRINT 1:PRINT:FOR I%=1 TO N%:READ A$:PRINT A$:NEXT I%:PRINT Z$;:SELECT PRINT 0:RETURN
190 ;
200 DATA " "," ","AN INTRODUCTION TO THE DBASIC ASSEMBLER DEMO:"," "," "
210 DATA "The DBASIC system disk includes a 68000 assembler and associated editor.  The"
220 DATA "assembler is very fast and - depending on YOUR limitations - very useful.  It"
230 DATA "is the same assembler that was used to develop DBASIC.  It's very fast because"
240 DATA "it is written in assembly and because a sort of 'RAM DISK' is used;  the"
250 DATA "source files are loaded only once although this is technically a two-pass"
260 DATA "assembler (or three-pass if you need a hard-copy listing)."," "
270 DATA "You will absolutely require an Epson-compatible hard copy printer to use this"
280 DATA "assembler.  Even if you don't want a hard copy listing, the error messages go"
290 DATA "to the hard copy printer only.  This assembler is not a toy and you have to"
300 DATA "have hard copy to do useful work."," "
310 DATA "This assembler was written to assemble source files developed by human beings"
320 DATA "using the included EDITOR.  No provision whatever has been made, or will ever"
330 DATA "be made, to accommodate source files developed by nonhumans (e.g. C compilers)."," "
340 DATA "You will need a 68000 assembly manual.  Motorola's is now up to the fifth"
350 DATA "edition but the fourth edition is O.K. (and in some ways to be preferred).  You"
360 DATA "can buy such a manual at (for instance) B. Dalton or you can get one free from"
370 DATA "your local Motorola sales office if you ask nicely."," "," "
380 DATA "The assembler automatically adapts itself to the memory size available (1/2 meg"
390 DATA "or 1 meg).  The 520 version will handle more source code all at once than most"
400 DATA "of you will ever write.  The 1040 version can almost assemble the entire DBASIC"
410 DATA "file - and DBASIC now runs over 700K of source code and over 57K of object"
420 DATA "code.  Even if you dedicate your entire life to developing assembly code,"
430 DATA "beginning now, by the summer of '88 we will presumably have a version of this"
440 DATA "assembler running on Atari's announced MegaST.  In other words, this is the"
450 DATA "biggest 68000 assembler you will ever need in your lifetime."," "
460 DATA "This assembler will work on either a one-drive or two-drive ST.  If a two-drive"
470 DATA "system is specified, then the editor and assembler will automatically maintain"
480 DATA "source and object files on the diskette in drive 2."," "
490 DATA "This is not a commercial package, just a demonstrator to illustrate the useful-"
500 DATA "ness of DBASIC.  You are accordingly encouraged to look at how it works.  For"
510 DATA "instance, the editor (very originally named EDITOR) is written entirely in"
520 DATA "DBASIC - there are no assembly language calls.  This means you can figure out"
530 DATA "how it works, and maybe customize special features for your own use."," "
540 DATA "The assembler is really three pieces of code.  One is the file-handler and the"
550 DATA "user interface, which is written in DBASIC.  This file is named ASM.  The other"
560 DATA "two pieces of code are for pass 1 and pass 2 of the assembly process.  Both of"
570 DATA "these pieces are written entirely in assembly, and both pieces of object code"
580 DATA "reside in a single binary file, whose name is AP1P2."," "
590 DATA "Finally, we have included about 77K of real, honest 68000 source code as an"
600 DATA "example.  That's about 1/4 of the available catalog space on the system disk!"
610 DATA "This source code is the real, honest, unmodified source code to pass 1 of our"
620 DATA "two-pass assembler, the part whose object code corresponds to roughly the first"
630 DATA "half of binary file AP1P2.  (No, you can't have the source code for pass 2.)."," "
640 ;
650 ;
660 ;
670 DATA " ","We want to see what the ST can do with a REAL assembly task, don't we ?  And,"
680 DATA "by coincidence, you're going to want a hard copy listing of our sample file"
690 DATA "so you can see, by example, how YOU should write source code."," "," "
700 DATA "The first thing you should do is make a copy of the DBASIC system disk and"
710 DATA "create a master assembler system disk.  This means you first run BACKUP to make"
720 DATA "a copy of the DBASIC system disk.  Next you SCRATCH all the files on the copied"
730 DATA "disk except AP1P2, EDITOR, ASM, P1F, PASS1, PASS1A, and PASS1B.  Now run COPY"
740 DATA "(not BACKUP) to create a system disk with only those 7 files on it.  This is"
750 DATA "your master assembler system disk.  You can either use this disk or make a"
760 DATA "working copy of it for the next steps:"," "," "
770 DATA "Boot your assembler system disk.  Turn on your Epson-compatible hard-copy"
780 DATA "printer.  RUN ASM.  When it asks you whether you are assembling a single file,"
790 DATA "reply 'N'.  When it asks you the name of the 'file of files', reply 'P1F'."
800 DATA "For now, we don't need a copy of the object file on disk, so just hit 'Return'"
810 DATA "without specifying a name for the object file to be saved.  The first time"
820 DATA "through, you might not want a hard copy, so just reply '1' to the two questions"
830 DATA "about the listing options."," "
840 DATA "If you've used a 68000 assembler before, you'll probably be surprised at how"
850 DATA "fast this runs, and assume that a very small file is being assembled.  Boy, are"
860 DATA "YOU going to be shocked !  Run the assembler again, and this time reply '3'"
870 DATA "and '4' to the listing options (we still don't need an object file).  Then get"
880 DATA "a book to read or something while your printer goes through a great big chunk"
890 DATA "of a redwood tree printing the source listing!"," "," "
900 DATA "Long before the listing has been completed, you'll have concluded that if"
910 DATA "you're going to do a lot of assembly work, you'll need a faster printer.  The"
920 DATA "best printer available for source listings (best = fast, quiet, inexpensive)"
930 DATA "is the C.Itoh C-810XP.  You can get this printer for a discount price of about"
940 DATA "$500.  If you aren't going to do much assembly programming, your current"
950 DATA "printer will do just fine."," "
960 DATA "(An MX-100 will print this listing in 77 minutes, an FX-80 in 45 minutes, the"
970 DATA "C-810XP takes 26 minutes, and a $2300 Mannesman-Talley 490 takes 16 minutes."
980 DATA "Just thought you'd like to know.)"," "," "
990 DATA "Now that you have a printout of the sample source code, you will doubtless be"
1000 DATA "interested in how you can enter that code, or code like it, using the EDITOR."," "
1010 DATA "You will notice that the first page starts with line 1, and has 60 lines.  If"
1020 DATA "you follow along the pages, the line numbers go up to #1459, and then start"
1030 DATA "over at #2.  Then they go up to #1139, and start over at #2, and go up to"
1040 DATA "#1287.  That's three files with 1459, 1139, and 1287 lines respectively.  There"
1050 DATA "are three files because the code is too big to fit into one file.  How big can"
1060 DATA "one file be, you ask ?  32K bytes maximum, we answer.  That's the biggest file"
1070 DATA "that can be handled using DBASIC's 'TXyyy' program statements.  See pages 49-51"
1080 DATA "and 265-275 of the manual.  If you execute a CAT (catalog) command, you will"
1090 DATA "see that these files occupy 27, 23, and 26 sectors (which is the same as 27K,"
1100 DATA "23K, and 26K since DBASIC uses 1K sectors).  32K is the maximum file size."," "
1110 DATA "Don't forget the little dinky file 'P1F'.  That's the 'file of files', which is"
1120 DATA "needed to assemble more than one file at a time.  That file has only three"
1130 DATA "lines;  the names of the 3 files to be assembled:  PASS1, PASS1A, and PASS1B."
1140 ;
1150 ;
1160 ;
1170 DATA " "," ","Take a look at lines 550-558 of the first file:  you'll not only see some"
1180 DATA "obsolete information (we TOLD you this was the assembler used to develop"
1190 DATA "HALGOL, er, DBASIC), you'll also see what is known as a 'comment' line.  Now"
1200 DATA "look at line 700.  That line has a label, an operand, a source, a destination,"
1210 DATA "and a comment.  Notice that the sections are nicely spaced out (in the pre-"
1220 DATA "cannabis sense);  we'll bet you're worried about getting all those spaces just"
1230 DATA "right when you enter lines like that.  Finally, take a look at line 701:  no"
1240 DATA "label, no source, no comment;  just an operand and a destination."," "
1250 DATA "The good news is, you don't have to worry about putting in all those spaces."
1260 DATA "You just have to put in ONE space at the right point(s) and the editor and"
1270 DATA "assembler will do the rest for you."," "," "
1280 DATA "The very first character you key on a line of source code is very important."
1290 DATA "If that character is a semicolon (;), then we have a comment line;  that is, a"
1300 DATA "line which is merely a comment for documentation purposes, and which should be"
1310 DATA "ignored by the assembler when generating label tables and object code.  An"
1320 DATA "example is line 681, another example is line 710 (in file PASS1)."," "
1330 DATA "If the first character of a line is a space character, then the next character"
1340 DATA "is the first character of a operand.  Line 701 is an example.  Yes, we know it"
1350 DATA "looks as if there are a lot more space characters than one at the start of line"
1360 DATA "701 before the operand, but that's just formatting that's supplied by the"
1370 DATA "program which prints the source listing.  You only need to key in one space."," "
1380 DATA "The operand in line 701 is 'JMP', or jump.  This is the machine language equiv-"
1390 DATA "alent of the BASIC 'GOTO' statement that all the computer scientists have been"
1400 DATA "telling you will rot your brain.  We'll discuss operands more later on."," "
1410 DATA "Then, a few space characters further over, is the destination 'ERROR'.  Right,"
1420 DATA "you only have to key one of those spaces in when you enter the line."," "
1430 DATA "Line 700 has a label, in this case 'SYNERR'.  That's an abbreviation for"
1440 DATA "'SYNTAX ERROR'.  You have to make up your own abbreviations because you only"
1450 DATA "have 8 characters to use for a label.  Why only 8 characters ?"," "
1460 DATA "We made a decision early in the game to use standard 8.5 by 11 inch paper for"
1470 DATA "our source listings.  At 80 columns per line, we have limited resources.  If we"
1480 DATA "use more than 8 characters for labels, we have to allocate fewer characters to"
1490 DATA "something else.  Take a look at lines 749, 769, and 771 for instance.  Most of"
1500 DATA "the professional programmers use wide paper and so have more than 80 characters"
1510 DATA "to work with, but special wide-carriage printers are needed and the source"
1520 DATA "listings are a lot wider and need more desk space to work with.  Remember, our"
1530 DATA "assembler is included as a no-charge demo with DBASIC.  You can always buy a"
1540 DATA "different assembler, but don't be surprised if it's one heck of a lot slower"
1550 DATA "than ours.  (Or you could write your own.  We did !)"," "," "
1560 DATA "Back to that label.  If the first character that you enter on a source line is"
1570 DATA "neither a semicolon nor a space, then it has to be the first character of a"
1580 DATA "label.  The first character of a label MUST be alphabetic (A-Z or a-z)."
1590 DATA "Subsequent label characters must be alphanumeric, which means the characters"
1600 DATA "0-9 are allowed as well as alphabetic characters.  The labels are case-"
1610 DATA "sensitive;  AAA, Aaa, and aaa are three different label names.  Spaces are"
1620 DATA "not allowed within labels;  like we said, subsequent characters MUST be alpha-"
1630 DATA "numeric."
1640 ;
1650 ;
1660 ;
1670 DATA " "," ","Hmm.  We have said that the first character of a source line must be a semi-"
1680 DATA "colon, a space character, or the first character of a label.  And the first"
1690 DATA "character of a label must be alphabetic.  Question:  what happens if the first"
1700 DATA "character of a line is neither a semicolon, a space, or alphabetic?  Answer:"
1710 DATA "you'll get a 'BAD LABEL CHARACTER ERROR', that's what.  Line 816 checks for a"
1720 DATA "space character, line 821 checks for a semicolon, and line 850 checks to see"
1730 DATA "that the first character of the label is alphabetic.  [REMEMBER: THE SAMPLE"
1740 DATA "CODE PROVIDED is THE CODE FOR THE FIRST PASS OF THE ASSEMBLER !]."," "," "
1750 DATA "Next, we have these things called 'operands'.  An operand is the name of an"
1760 DATA "operation to be performed by the 68000 microprocessor.  As the developers of"
1770 DATA "the 68000, Motorola got to define the names of the operands.  To know what the"
1780 DATA "names are, you will have to obtain a Motorola programming manual.  How you do"
1790 DATA "that is YOUR problem (gee, if we charged $495 for DBASIC, we could probably"
1800 DATA "toss in a free Motorola manual, even if we did have to pay $20 for it)."," "
1810 DATA "Besides operands, the assembler also supports what are called 'pseudo-ops', or"
1820 DATA "pseudo-operands.  These are instructions to tell the assembler to do something."
1830 DATA "For instance, look at the first page of the PASS1 source listing:  the last"
1840 DATA "line number is 60.  The first line number on the next page is number 62.  Guess"
1850 DATA "what line 61 of the source is ?  Right, it is the pseudo-op 'PAGE', which tells"
1860 DATA "the assembler listing code to send a form-feed to the printer at that point."," "
1870 DATA "Just as Motorola got to define the names of the operands (as well as what the"
1880 DATA "microprocessor does with those operations), WE get to define our pseudo-ops"
1890 DATA "and what they do.  If you don't like the names of the Motorola 68000 operands"
1900 DATA "or what they do you get to use a different microprocessor;  it's a free"
1910 DATA "country.  If you don't like the names of our pseudo-ops or what they do you get"
1920 DATA "to use - or write - a different assembler.  It's still a free country."," "," "
1930 DATA "Lines 120 to 398 of PASS1 list the names of the Motorola operands and our"
1940 DATA "assembler pseudo-ops in alphabetical order;  our pseudo-ops are noted as"
1950 DATA "comments."," "," "
1960 DATA "Here's what our pseudo-ops do:"," "
1970 DATA "ASC is used to generate binary byte(s) corresponding to the ASCII character(s)"
1980 DATA "inside quotes.  See line 121, for instance.  If single quotes are used ('), the"
1990 DATA "most significant bit of the byte(s) will be set."," "
2000 DATA "DC is used to specify a byte, word, or long-word value.  See line 120.  DC.B"
2010 DATA "allocates a byte value, DC.W allocates a word value, and DC.L allocates a long-"
2020 DATA "word value.  Also see lines 94 and 95."," "
2030 DATA "DS reserves a number of bytes, words, or long-words.  These are filled by nulls"
2040 DATA "($00) by the assembler.  The sample code provided does not use DS, so here are"
2050 DATA "some examples:"
2060 DATA "                   DS.B 17  reserves 17 bytes"
2070 DATA "                   DS.W 34  reserves 34 words, or 68 bytes"
2080 DATA "                   DS.L 5   reserves 5 long-words, or 20 bytes"," "
2090 DATA "EQU means 'EQUATE'.  It is used to set a label equal to a value.  The value is"
2100 DATA "most commonly used as an address, but it can also be used as a numeric value."
2110 DATA "See lines 25 through 67 of PASS1, for instance."
2120 ;
2130 ;
2140 DATA " "," ","FWRD is a toughie.  To know how it works, you have to know that (for instance)"
2150 DATA "a 68000 JUMP can use a word or a long-word address, at the machine-code level."
2160 DATA "When our assembler comes across a line of source which is JUMP LABEL, it looks"
2170 DATA "to see whether LABEL has been defined yet.  If LABEL has been defined, then"
2180 DATA "our assembler knows what the address of LABEL is, and thus whether to use the"
2190 DATA "short or long form of the JUMP instruction.  The long form takes two more bytes"
2200 DATA "of code and four more clocks to execute, which is why the short form is used"
2210 DATA "whenever possible.  But if we have what is known as a 'forward reference',"
2220 DATA "meaning that LABEL has not yet been defined, then the assembler doesn't know"
2230 DATA "whether to allocate one or two words to the address.  But... it HAS to know !"
2240 DATA "So there is a flag which determines whether one or two words are allocated."
2250 DATA "This flag is initialized to the long-word value when the assembler starts (see"
2260 DATA "line 750 of PASS1).  The value of this flag can be controlled by the programmer"
2270 DATA "using the FWRD (forward) pseudo-op:"
2280 DATA "                FWRD W  sets the short form of the address"
2290 DATA "                FWRD L  sets the long form of the address"," "
2300 DATA "GAP is also not used in the example source.  It can be used in conjunction with"
2310 DATA "ORG statements to control the maximum size of the blank space (null bytes) that"
2320 DATA "can occur between the end of the current code and a new address specified by an"
2330 DATA "ORG pseudo-op.  The maximum size of this gap is initialized to 1024 (line 752)."
2340 DATA "The gap can be resized upward to (for instance) 4K by this line:"
2350 DATA "                GAP $1000"
2360 DATA "or              GAP 4096"," "
2370 DATA "LIST controls, along with options and code in program ASM, whether portions of"
2380 DATA "source code are or are not listed.  Program ASM also has provisions for over-"
2390 DATA "riding LIST pseudo-ops, via the never-list or always-list options.  Otherwise,"
2400 DATA "LIST turns on the hard-copy source listing and NOLIST turns off the hard-copy"
2410 DATA "source listing.  This can be a blessing when you are developing assembly code"
2420 DATA "and only have a slow printer;  you just list the section(s) of the code which"
2430 DATA "are of current interest."," "
2440 DATA "NOLIST was discussed in the above paragraph."," "
2450 DATA "ORG sets the address at which the source code is assembled.  See line 70 on the"
2460 DATA "second page of the example listing, for instance."," "
2470 DATA "PAGE forces a form-feed during a hard-copy source listing."," "
2480 DATA "SHORT has no relevance with 99.999% of all 68000 systems, including the STs."
2490 DATA "Ignore it.  (Our DTACK boards had a hardware peculiarity which required this"
2500 DATA "pseudo-op.)"," "
2510 DATA "SYNC forces an even address during assembly.  If the address is not even, a $00"
2520 DATA "is inserted to advance the address, and if the address is already even then no"
2530 DATA "action is taken.  See lines 399 and 698 of PASS1;  SYNC is commonly used after"
2540 DATA "ASCII tables which may or may not have an even number of bytes.  (An implicit"
2550 DATA "SYNC is also forced by the assembler at some times, under certain conditions."
2560 DATA "What times and what conditions is a quite complex matter.)"," "
2570 DATA "TITLE is not implemented.  In fact, the guy who programmed the assembler (me)"
2580 DATA "has forgotten what it was for (nobody's perfect)."," "," "
2590 DATA "And that's all the psuedo-ops.  Next page:  using the EDITOR."
2600 ;
2610 ;
2620 ;
2630 DATA " "," ","The EDITOR is written entirely in DBASIC;  you are encouraged to get a listing"
2640 DATA "and take a look at the code.  Just LOAD EDITOR, SELECT LIST 1, LIST.  The"
2650 DATA "listing is only three pages long.  Don't forget to SELECT LIST 0 afterwards"
2660 DATA "(just run the cursor up to SELECT LIST 1, change the 1 to a 0, and hit Return)."," "," "
2670 DATA "The EDITOR has the following commands:  ADD, APPEND, CUT, DELETE, DR, EDIT,"
2680 DATA "EXIT, INSERT, LIST, LOAD, OPEN, PASTE, PRINT, and SAVE."," "
2690 DATA "ADD places you in the mode which is primarily used to input source code.  It's"
2700 DATA "the same as the INSERT mode, except that it automatically places you at the end"
2710 DATA "of the source code which is currently in memory.  If there's nothing in memory,"
2720 DATA "then you'll be placed at line 1.  To exit the ADD mode, just hit Return without"
2730 DATA "entering anything on a given line."," "
2740 DATA "APPEND FILENAME will load the source code file 'FILENAME' and append it to the"
2750 DATA "end of the source code currently in memory, first checking to see that the"
2760 DATA "result will not overflow the 32K text array."," "
2770 DATA "CUT is used with PASTE to manipulate (move around) blocks of code, usually"
2780 DATA "several lines at a time.  CUT will place M lines of code which are currently in"
2790 DATA "memory, beginning with line N, into a temporary buffer.  The lines can be"
2800 DATA "either CUT or COPIED.  If CUT, they are removed from memory after being placed"
2810 DATA "in the temporary buffer.  If copied, the lines are copied to the temporary"
2820 DATA "buffer and are also left in memory.  Also, see PASTE."," "
2830 DATA "DELETE will delete a line or lines of source code from memory.  'D' may be used"
2840 DATA "as an abbreviation for DELETE.  To delete line 75, the syntax is D75.  To"
2850 DATA "delete lines 100 to 200 inclusive, the syntax is:  D100-200."," "
2860 DATA "DR is used exactly like the DBASIC DR command and for the same purpose.  Most"
2870 DATA "folk who are serious about developing large assembly-language projects wind up"
2880 DATA "using a two-drive system with the ASM and EDITOR programs on drive 1 and the"
2890 DATA "source and object files on a separate diskette in drive 2.  By issuing a 'DR 2'"
2900 DATA "command, the editor will subsequently use drive 2 for all disk file operations"
2910 DATA "(APPEND, LOAD, SAVE).  A 'DR 1' command will switch back to drive 1.  By"
2920 DATA "issuing 'DR 1' and 'DR 2' commands alternately, it is possible to transfer"
2930 DATA "source files, one at a time, from the diskette in drive 1 to the diskette in"
2940 DATA "drive 2 or vice versa.  If you have a one-drive system, you can ignore DR."," "
2950 DATA "EDIT permits editing (changing) an existing line of source code in memory.  'E'"
2960 DATA "is an acceptable abbreviation for EDIT.  To EDIT line 100, the syntax is"
2970 DATA "'E100'.  To EDIT lines 50 to 65 inclusive, the syntax is E50-65.  Line 50 will"
2980 DATA "be edited first.  After making whatever changes (if any), hit Return and you"
2990 DATA "will find yourself in line 51.  This continues until, after EDITing line 65,"
3000 DATA "hitting Return will place you back in the command mode."," "
3010 DATA "EXIT dumps you out of the EDITOR and back into the DBASIC environment; all"
3020 DATA "source code which has not been SAVEd will be lost."," "
3030 DATA "INSERT allows you to enter a line or lines of source code in the middle of the"
3040 DATA "lines of source code in memory.  'I' is an acceptable abbreviation for INSERT."
3050 DATA "If you have 500 lines of source in memory, and you want to insert one or more"
3060 DATA "lines at line 137, the syntax is I137.  You will be placed in (new) line 137."
3070 DATA "After entering the new line 137, you will be placed in line 138.  To exit the"
3080 DATA "INSERT mode, just hit Return without entering anything on a given line.  You"
3090 DATA "can even do this on the first line to be entered, in case you change your mind."
3100 ;
3110 ;
3120 ;
3130 DATA "LIST will LIST a line or lines of code to the CRT.  'L' is an acceptable"
3140 DATA "abbreviation for LIST.  To list line 100, the syntax is L100.  To list lines"
3150 DATA "100 to 120, the syntax is L100-120.  Remember, you only have 25 lines on your"
3160 DATA "CRT.  The hard copy equivalent of LIST is PRINT."," "
3170 DATA "LOAD FILENAME will load the source code file FILENAME into memory.  Any source"
3180 DATA "code which was previously in memory will be lost.  By executing LOAD FILENAME,"
3190 DATA "the file name FILENAME becomes the default filename, which can be useful when"
3200 DATA "time comes to SAVE the file  (see SAVE).  LOADing a file has no effect on the"
3210 DATA "contents (if any) of the CUT buffer."," "
3220 DATA "OPEN FILENAME does nothing but assign 'FILENAME' to the default filename, which"
3230 DATA "can be used later by the SAVE command."," "
3240 DATA "PASTE is used in conjunction with the command CUT.  Once a line or lines have"
3250 DATA "been placed into the temporary CUT buffer, the command PASTE can place those"
3260 DATA "lines into the currently loaded source code at a given location.  You may"
3270 DATA "consider PASTE to be an automated INSERT, if you wish.  PASTE does not destroy"
3280 DATA "the contents of the CUT buffer."," "
3290 DATA "PRINT is the hard copy equivalent of the LIST command.  'PR' is an acceptable"
3300 DATA "abbreviation for 'PRINT'.  The syntax to PRINT lines 100-200 is PR100-200."
3310 DATA "Remember, PRINTing the source code is not the same as getting a source listing"
3320 DATA "from the assembler (ASM), but the format is similar.  PRINT is mostly used to"
3330 DATA "get a quick hard-copy listing for proofreading prior to performing an assembly"
3340 DATA "to get the actual source listing.  (Dumb mistakes don't stop the PRINTing, but"
3350 DATA "they DO stop the assembled source listing from even starting !)."," "
3360 DATA "SAVE FILENAME saves the lines of source code in memory to disk in the file"
3370 DATA "whose name is FILENAME.  If FILENAME is omitted (in other words, if the command"
3380 DATA "SAVE is issued with no filename), then the default filename will be used.  If"
3390 DATA "you are currently editing a source file which was previously LOADed, then"
3400 DATA "the default filename is the name of the file which was previously loaded."," "," "
3410 DATA "PRUDENT PERSONS WILL HEED THIS ADVICE:"," "
3420 DATA "This EDITOR has not been completely idiot-proofed.  It is entirely possible to"
3430 DATA "spend several hours inputing, editing, and modifying a lot of source code"
3440 DATA "without ever SAVEing it to disk.  And then you do something dumb:  POOF !"
3450 DATA "There goes all the hard work you did !  This is commonly known as a dumb$#!+"
3460 DATA "mistake, because you are a dumb $#!+ if you do that."," "
3470 DATA "The reason for the simplified SAVE, using that default name, is that every 15"
3480 DATA "minutes or so, you can simply key SAVE (Return).  It only takes a second or so."
3490 DATA "That way, when you do something dumb, you've only lost what you did since the"
3500 DATA "last SAVE.  If you choose to disregard this advice, you're gonna get what you"
3510 DATA "deserve, you dumb $#!+, and probably sooner than later."," "," "
3520 DATA "GETTING STARTED, OR BEGINNING AT THE BEGINNING"," "
3530 DATA "The biggest problem with working with assembly code is getting started.  Heck,"
3540 DATA "you have to learn how to use an editor to create source code, and then use an"
3550 DATA "assembler to generate object code, and then save that object code somehow to"
3560 DATA "a binary disk file, and then somehow load and run that file.  This is sort of"
3570 DATA "like riding a bicycle - impossibly difficult the first time, but trivially"
3580 DATA "simple afterwards."," "
3590 DATA "Starting on the next page, we offer a bicycle riding lesson."
3600 ;
3610 ;
3620 ;
3630 DATA " "," ","HOW TO ASSEMBLE GOOD, a beginner's lesson:"," "," "
3640 DATA "What we are going to do is generate machine code to multiply two numbers, save"
3650 DATA "that code to disk, and load and run it from the DBASIC environment.  This isn't"
3660 DATA "too exciting, but you gotta start somewhere!  (The objective of a first bicycle"
3670 DATA "ride is not to travel from Philadelphia to Denver;  the objective is to not"
3680 DATA "fall off !)"," "
3690 DATA " 1) Boot your DBASIC system disk, CLEAR memory, and RUN EDITOR.  Use 1 drive."," "
3700 DATA " 2) Key the command 'OPEN MULTS' (assign filename MULTS = MULTiplier Source)."," "
3710 DATA " 3) Key the command 'ADD'.  You should find yourself in line 1."," "
3720 DATA " 4) Enter one space character, then 'MOVE', then another space character, then"
3730 DATA "    '#$7777,D0', then Return.  You should find yourself in line 2.  Hit Return"
3740 DATA "    again to exit the entry mode.  Line 1, which you just entered, should still"
3750 DATA "    be on the screen, and it should look like this (underlines used for spaces):"," "
3760 DATA "    1__MOVE_#$7777,D0"," "
3770 DATA "    (Yes, there should be TWO spaces between the 1 and the MOVE.  The first one"
3780 DATA "    is the one entered automatically by the EDITOR to separate the line number"
3790 DATA "    from the label, and you entered the second space to indicate that there is"
3800 DATA "    no label on that line.)"," "
3810 DATA " 5) Key the command LIST.  Line 1 should be listed something like this:"," "
3820 DATA "                  1            MOVE     #$7777,D0"," "
3830 DATA " 6) See ?  We TOLD you that the editor/assembler would enter all those spaces"
3840 DATA "    for you !  Now we can enter four more lines without worrying about those"
3850 DATA "    extra spaces."," "
3860 DATA " 7) Key the command 'ADD' again.  You should find yourself in line 2."," "
3870 DATA " 8) Repeat step 4, except with '#$8888,D1'."," "
3880 DATA " 9) You should now be in line 3.  Enter a space char, then 'MOVE', then another"
3890 DATA "    space char, then 'D1,D7', then Return."," "
3900 DATA "10) You should now be in line 4.  Enter a space char, then 'MULU', then another"
3910 DATA "    space character, then 'D0,D2', then Return."," "
3920 DATA "11) You should now be in line 5.  Enter a space char, then 'TRAP', then"
3930 DATA "    another space character, then '#12', then Return."," "
3940 DATA "12) You should be in line 6.  We've finished entering source code, so hit"
3950 DATA "    Return again to return to the command mode."," "
3960 DATA "13) Key the command 'LIST'.  What you should get on the screen is something"
3970 DATA "    like this:"
3980 DATA "                  1            MOVE     #$7777,D0"
3990 DATA "                  2            MOVE     #$8888,D1"
4000 DATA "                  3            MOVE     D1,D7"
4010 DATA "                  4            MULU     D0,D2"
4020 DATA "                  5            TRAP     #12"," "
4030 ;
4040 ;
4050 ;
4060 DATA " "," ","14) Oops !  Line 3 is wrong.  We should have told you to MOVE D1,D2 instead of"
4070 DATA "    MOVE D1,D7.  So key the command E3 (EDIT line 3), and run the cursor over"
4080 DATA "    to the 7 and hit 2, then Return.  Then repeat step 13.  This time you"
4090 DATA "    should have the right code.  If any of the lines look wrong, use the EDIT"
4100 DATA "    command to fix them.  After all, you know how to EDIT now, right ?"," "
4110 DATA "15) When the five lines look the way they should when you LIST them, it's time"
4120 DATA "    to key 'SAVE'.  We don't have to specify the filename because we set that"
4130 DATA "    up back in step 2."," "
4140 DATA "15) We are now done with the EDITOR.  Key the command EXIT to, uh, EXIT the"
4150 DATA "    EDITOR."," "
4160 DATA "16) Now to assemble the file.  RUN ASM."," "
4170 DATA "17) Acknowledge the printer message by keying Return - but not until after"
4180 DATA "    you've turned on the printer !  Then, use 1 drive."," "
4190 DATA "18) When ASM asks if you are assembling just one file, answer 'Y', Return."," "
4200 DATA "19) When ASM asks for the name of the file, answer 'MULTS', Return.  (Remember"
4210 DATA "    step 2 ?)"," "
4220 DATA "20) When ASM asks for the filename of the code to be saved, reply 'MULTOBJ',"
4230 DATA "    Return.  (MULTOBJ = abbreviation for MULTiplier OBJect code.)"," "
4240 DATA "21) When ASM asks for the source listing option, reply '3', Return."," "
4250 DATA "22) When ASM asks for the label table listing option, reply '1', Return (there"
4260 DATA "    ain't no labels)."," "
4270 DATA "23) As soon as you entered Return in step 22, the assembly process started.  It"
4280 DATA "    sure don't take long, do it ?"," "
4290 DATA "24) ASM saves the object code to disk BEFORE printing the source listing.  As"
4300 DATA "    soon as the source listing, all five lines of it, is done then the assembly"
4310 DATA "    process is done.  Now it's time to run that object code !"," "
4320 DATA "25) Key CLEAR.  That clears the ASM program from memory so we can write a new"
4330 DATA "    DBASIC program."," "
4340 DATA "26) You have to enter this real complicated two-line DBASIC program:"," "
4350 DATA "    10 BLOAD MULTOBJ,$20000"
4360 DATA "    20 CALL $20000"," "
4370 DATA "27) Now key RUN  (this is called the moment of truth !)."," "
4380 DATA "28) You should see what is called a 'register dump' on the screen.  The lower"
4390 DATA "    word of D0 should be 7777 (the '$' is implicit), the lower word of D1"
4400 DATA "    should be 8888, and register D2 should contain the long-word (4-byte)"
4410 DATA "    result of performing an unsigned multiply (MULU) of $7777 times $8888."," "
4420 DATA "29) Assuming that what you have on the screen matches what step 28 says should"
4430 DATA "    be on the screen, congratulations !  You just rode that bicycle without"
4440 DATA "    falling off !  We wish you equally good luck in the future..."
