Adam News Network volume 97 issue 11

Return to adamcon.org | Adam News Index | Volume 97

In this issue:

• 463pg2 [ 5 kb]
• cis-xmas [ 3 kb]
• gene-ac9 [ 5 kb]
• pjh [ 3 kb]
• readme [ 3 kb]
• rich-rep [ 4 kb]
• rich06 [ 24 kb]
• rich13 [ 25 kb]
• rich20 [ 18 kb]
• ron_1 [ 12 kb]
• ron_2 [ 6 kb]
• ron1021 [ 5 kb]
• ron15oct [ 5 kb]
• subscrib [ 1 kb]
• will [ 6 kb]
• will3 [ 3 kb]
• will4 [ 1 kb]
• willn [ 1 kb]
• xmaspics [ 2 kb]
• zonker [ 2 kb]
• zonker2 [ 1 kb]

Article: 463pg2

At the last meeting we spent most of the time trying to get Joe Alford's ADAM hooked up to his DM printer. This was not successful. Not sure what the problem is. We'll try again this month. If Joe gets his ADAMServe software we'll also see if we can get his ADAM to access his IBM hard drive. This months meeting will be on Friday the 3rd. and the November meeting will be held on Friday the 7th. Hope to see you at the meetings.

                    Jerry V.

=====================================

KEEPING IN TOUCH

At the last three ADAMcons there have been several discussions on what is the best way for us ADAMites to keep in touch and to get ADAM related information out to the ADAM community. It has been pretty much decided not to put all our eggs into one basket. I personally think these concerns are of no real consequences. Think back five or six years. There were several widely circulated newsletters. ANN had a good circulation. CompuServe was widely used. There were several privately run BBS's. But look at today. We're down to two newsletters, one or two BBS's, there's not as much chatter on CompuServe. What's going on? It's called evalution. The ADAM community is like all other entity. It evolves. As our numbers decline so does everything else. Please don't get me wrong. I'm not trying to paint a picture of glum and doom for ADAM communication. It just may be moving toward the Internet. A year ago if you would have told me I would be on the Internet I would have told you that you were nuts. But I am. I think Rich and Frances Clee may have told you the same thing. I have no intentions of leaving CompuServe. AOL has purchased CompuServe. Therefore will CIS continue to support the 8 bit computer? If not, where do we go? Like it or not things are changing. The point that I really want to make is this. No matter how our communications evolve, we must keep in touch.

                    Jerry V.

=====================================

NEXT MONTH

It's rare indeed when I can tell you what will be in the next 463 ADAM newsletter. The November issue will have Richard Clee's and Ron Mitchell's ADAMcon 09 keynote address, more articles by Dr. D. (Rich Drushel). Yes more AC09 color pictures. And hopefully a few suppresses. BTW ... Don't forget, the November meeting is on Friday the 7th.

=====================================

NEW MEMBER

I would like to welcome Geoff Oltmans from Newton, Al. to our little group.

Geoff, feel free to speak up when ever the urge strikes you. Again, welcome aboard.

                         Jerry V.

=====================================

Color Pictures

I've tried several times to copy Bart Lynch's convention pictures for use in this newsletter, I could never do them justice until now. Thanks Zonker for all the great pictures.

                         Jerry V.

=====================================

ANN HOLIDAY CARD

Ron Mitchell will be putting the ANN holiday card together again this year. This information was in a message that Ron posted to Pat Herrington on CompuServe. Ron will be asking for some technical support. But the biggest support Ron can get is from us. That is for us to set down and design a 10k PowerPAINT picture for the holiday card.

Your picture need not be anything fancy. In fact some of the most enjoyable pictures have been done by Bart Lynch. I still laugh out loud every time I see Bart's picture of Santa stuck in the chummily.

So lets all get in gear and make this years card the best yet. Send your picture to Ron Mitchell as soon as you can. There is a deadline for getting the card out. His address is on the inside cover of this newsletter.

                         Jerry V.

=====================================

ANN DISK

If you don't receive the ANN disk your missing out. Yes, most of the text in this newsletter either comes from the ANN disk or goes to the ANN disk. So there is some repetition, but there are things on the ANN disk that I can't put in the newsletter. Case in point. The ANN Holiday Card. Bob Slopsema is doing an excelent job of getting the ANN disk out in a timely manner. (Some of his mailers may be sluffing off, but Bob is doing his part.) To receive the ADAM News Network disk send $25 to: Bob Bair 6552 N 400 E Kendallville, IN. 46755

rt Lynch. I still laugh out loud every time I see Bart's picture of Santa stuck in the chummily.

So l ÿ

Return to index

Article: cis-xmas

This is from Joe Mirando, a displaced Atari computer user who has come online with the Sun evening conference group and fits right in with the rest of us. They are also an orphaned group.

I happened to mention this poem to Sysop PJ, who asked that, if I ever found it, I post it in the ADAM area. Late in December of 1995, it was announced that ASCII access of CompuServe was coming to an end and that HMI (CompuServe's proprietary format) would become the standard. Remember, this was shortly before Project Red Dog, which will provide HTML access) was announced. Red Dog is coming closer to completion as you read this, so pay attention! <g> I know that it's not even close to the holidays, but if I wait another three months to post this, I'll loose it.

Originally posted in the Atari Computing Forum on Sunday December 24, 1995 Re-posted with the permission of the author

          
                  The Day Before Christmas
                       by Joe Mirando

Return to index

Article: gene-ac9

by Gene Welch

The first highlight of the trip to Grand Rapids, Michigan was Northwest Airlines. I flew them to the convention this year and I arrived in much better shape than I had last year for 08, when I flew with Southwest Airlines.

Another highlight was seeing everyone from AdamCon 08. Although there were a few missing faces from last year, there were a few new faces to make up for it.

As with previous 'Con's, the hotel accomodations were excellent. Bob and Judy Slopsema did a fine job of planning this event. There was plenty of good food, and the rooms were nice as well.

There was a Radio Shack nearby that I gave some of my money too, upon my arrival. I had brought the wrong video cable for hooking my Lap-Top ADAM to the television set in my room. It only took a few minutes to run across the street to the shopping center and pick up the right one. I know this does not sound like it should be a highlight, but this is the first time I have left the Hotel and went shopping during an AdamCon.

I spent a couple of hours in my room with Dale Wick, he demoed his new compiler and taught me a few tricks with TDOS and ML programming.

The food was outstanding, and the Sunday Brunch was an enormous spread. I made several trips to refill my plate, though I was unable to keep up with some Adamites.

I had a great time learning to use Dale Wick's Micro Compiler. I had three supervised sessions with it. It is an amazingly easy to use compiler. I can't wait to get my hands on the final version (we were using v0.77).

Ron Mitchell's MIDI session was quite good. Ron brought a lot of equipment, and walked us through SEQUEL, the sequencing software. He also demoed the DYNOMITE SOUND DIGITIZER. I own one of these, but haven't used it in some time. That should change, now.

Another highlight with Ron was spending an hour or two in his room with the DYNOMITE SOUND DIGITIZER. I have learned a couple of tricks, and enjoyed rediscovering this unique piece of ADAM hardware.

Just thought of another good one. Bob Slopsema, relaxed and in charge of the 'CON running around in his socks. I even got a picture of it during the Sunday night Banquet.

Rich Drushel shared alot of juicey ADAM trivia and some unique ADAM hardware and generally neat stuff. Hopefully he will be writing about it, possibly in his weekly articles.

Rich also brought along a LEGO robot from his Engineering course. It was a big hit.

Bob Bair gave many impromptu one-on-one sessions on ADAMBOMB 2. I learned a few tricks from Bob, as did many other Adamites. I was also relieved to see that I am not the only one who has had a tough time conquering this great game.

I enjoyed all of the breakfast speeches, but I thought that Rich Clee's was the best. Hopefully it will be published so that every Adamite can enjoy it as well.

P. J. Herrington led a session on PowerPaint that had her feilding questions on this very popular software. I learned a new trick myself.

Watching Herman Mason try to resurrect Bart Lynch's dead Hard Drive was a highlight I won't soon forget.

Neil Wick got ADAMEM, the ADAM Emulator running on his laptop computer. He had ADAMCALC, and several cart games going quite well.

I finally got the SHOW.GIF viewer working, with a little help from Dale Wick(its author). I have GIF picture files(color) of my two children(Melissa and Andrew) that I have been waiting to see on my ADAM.

Bart Lynch's TDOS to EOS session was great. He had it on video tape and was able to go over the important parts over and over again, 'til we understood what was going on.

Rich Drushel ran a speed test between Dale's MIC compiler and the SmartBasic interpretor. The compiler won hands down. It was 15 to 20 times faster. Now that's amazing.

An unexpected Adamite crashed the 'Con. A fellow by the name of David Ramsey learned of AdamCon from the Internet and stopped by to chat for a while.

Bob Slopsema was inducted into the GALLERY of HONOUR. Bob really deserves this distinction. He has put a lot of work into the ANN, and also Adamcon 09, lately.

Also inducted were Eric Danz and Ed Jenkins, both deserving fellows.

Now, I have saved my biggest highlight for last. You see, there were four inductees this year. The three above and ME. Yes, that's right, me. I, Gene Welch, am very grateful to everyone for placing me in the Gallery with all the great Adamites that have made it possible for me to get the most enjoyment possible from my ADAM computer.

                    Thank You.

Ric

Return to index

Article: pjh

20-Oct-97 22:27:22 Sb: #51693-#CHANGES
Fm: Sysop/*PJ (ADAM) 76537,1271
To: Lee Lightfoot/Apricot 72730,1006 (X)

Does your machine do CP/M? I believe that Lynx is a CP/M program. It's not the only one available but it's the one I've most recently seen. Internet was originally a government project, initiated I think during the early years of the Cold War, in order to insure that messages of importance could be received by various stations even if one or more of those stations had been wiped out by a bomb. That's a kind of nutshell thingie there. But soon scientists discovered its usefulness, and multiply redundancy insured that their messages would arrive eventually despite any downtime from any of the intermediate stations. Soon colleges and libraries and special interest groups became users of the system. Early messages from small computers included such gems as "what kind equpmt u use?" and I'm pretty sure that's where many BBS acronyms got started. It all sounded like a bunch of telegrams written by people trying to get the most out of ten words. Anyway, over the past few years, everybody and his Uncle George has jumped onto the net and practically ruined it for the people who had been using it for decades. And then the Web came out and got really commercial. Now we get junk mail we hate, and that's progress. I tell people that I remember fondly the time when I could invariably choose how much water I did or did not want in the tub, simply by inserting a rubber stopper in the drain which cost maybe a dime and did not require the services of a plumber to install. I feel much the same way about the fancy, fallible, and infuriating abundance of fancy drain gimmicks as I do about the f,f, & i innovation (s) that plague a sweet and simple system which everybody wants to make cute and complicated... and EXPENSIVE. I still prefer my own software for conferencing, and can do things that the fancy new stuff won't do. If it ain't broke, for crissake don't fix it. I can see using the new stuff for new applications, but for the stuff that worked perfectly fine as it was and took less time and space, I really like the tried and true and simple and effective and cheap. PJ <soapbox mode OFF> :D :D :D :D

Return to index

Article: readme

              ADAM NEWS NETORK NOVEMBER DISK

****************************************************************

	463pg2        Page # 2 from the Oct 463rd ADAM club newsletter

	cis-xmas      A contribution from one of our fellow comrades in
		      arms in the Club forum.  An ATARI computer orphan

	GeneAC9       "My ADAMCON Highlights" by Gene Welch

	PJH           PJ Herrington writes her view of the Internet of
		      today.......shared by many, many others I think

	Rich-rep      Rich Drushel replies to Ron Mitchell's comments on
		      one of Rich's weekly articles on ADAM

	Rich06oct     Rich Drushel's article dated Oct 6th

	Rich13oct     Rich Drushel's article dated Oct 13th

	Rich20oct     Rich Drushel's article dated Oct 20th

	Ron#1         RonsWeek'n'ADAM  dated Oct 5th

	Ron#2         Ron Mitchell's reply to Geoff Oltmans concerning
		      some thoughts on RonsWeek of Oct 5th

	Ron15oct      Ron Mitchell's Week'n'ADAM dated Oct 15th

	Ron21oct      Ron Mitchell's Week'n'ADAM dated Oct 21st

	Subscribe     Instructions for subscribing to the monthly mailing
		      of the ADAM NEWS NETWORK

	Will          From Will Nerini, "OS, GUI & why ADAM shouldn't be
		      a doorstop"

	Will3         Will's reply to Ron MItchell about Will's message
		      of "Being in ADAM Heaven"

	Will4         Will Nerini needs some help on disk formatting

	WillN         "ADAM Heaven" and why Will Nerini is in it!

	Zonker        Zonker writes to Rich Drushel concerning Rich's
		      Oct 10th article

	Zonker2       Zonker GIVES some advice to Ron Mitchell who is
		      looking for a special twist on a program

	XmasPics      A reminder to submit your christmas PP pics to
		      Ron for publication in the annual christmas card

	ReadMe        This file

Return to index

Article: rich-rep

Ron:
> It brings to mind an anecdote that was sufficient to convince
me that I might be better off finding another hobby. I have not written a serious line of code since this particular experience, not because I didn't want to, but for reasons I'll get to in a moment.

[story of being called on the carpet for "spaghetti code" deleted]

Ron, this is terrible to hear! I hadn't realized that the term had a personal meaning that cut too close to home.

Ron:
> As mentioned earlier, I haven't written a line since.

This is our loss, and yours, because you're clearly clueful enough to be a good programmer.

> My method was the 'code-now-plan-later-fly-by-the-buttseat'
school of computer programming.

This is a necessary "larval" stage for programmers. Experience usually forces you to outgrow it (as your desire to write more complicated programs makes you write them, and find it's too hard without some kind of preplanning). But the need for quick and dirty hacks never goes away. You simply must recognize when it's worth it to preplan and when to just type it in as you think of it.

Ron:
>It was a method that suited my purposes at the time. I
certainly did have a whole pile of fun playing about, and I discovered a whole pile of information about what wouldn't work. Those were the good old days.

Ron, I strongly encourage you to go back to those "good old days" and roll around in that pile of fun. Knowing what you do now (compared to then), even your improvisations will have some structure to them, without much conscious effort.

        [begin Rich's Philosophy of Life spiel]

It is better to be a doer than a spectator. With computers as a hobby, this means it's better to be a programmer than simply an end user. People who are only users are ultimately limited by what others manage to serve up for them. If you can learn to take the bull by the horns, so to speak, you can serve yourself if nobody else is giving you just what you want.

[end PHIL 101; your mileage may vary, there will not be an exam]

So, please consider giving programming another go...and don't take my Essentials of Programming Style comments personally. You should see the Microsoft BASIC 3.0 code for the Star Trek game I wrote for the IBM-PC in 1985-1988 (before QuickBASIC 4.5 made the need for line numbers go away). Or the data analysis programs I wrote (also in BASIC 3.0) for my undergraduate research project in 1983-1984. *Those* are spag- hetti. The Star Trek game in particular would be nice to port to the ADAM, but it would be easier to rewrite it. Also, all the patches that I have done to make ADAMlink V and the hard disk version of PowerPaint, not to mention the patches to Smart- BASIC 1.0 to make 1.x--in their native form, those are unmain- tainable spaghetti. ADAMserve and the EOS-8 project are the only large ADAM programming projects I have written from the ground up according to the "rules". (My current research pro- grams are all in "good style", too, of necessity, since I have to regularly maintain and upgrade them.)

        *Rich*

Return to index

Article: rich06

by Richard F. Drushel (drushel@apk.net)

I. What is a Bank-Switched EOS Operating System?

The last issue of TWWMCA (9709.30) mentioned in general terms some of the advantages to allowing the EOS operating system to move into expansion RAM (XRAM). I invited public comment on the idea; and in response, I received the following query from Bart "Zonker" Lynch:

>rich, could you put your "explanation hat" on and have a go at making this
>a bit more clear? i want to make sure i grasp the concept of what you are
>proposing before i make any comments. please remember to K.I.S.S! :)
>-zonker

I will try to clarify some of the technical issues, implications, and limitations of such an EOS redesign. First some basic facts:

II. ADAM Memory Organization.

The Z80 microprocessor of the ADAM can access 64K of memory. This memory can be RAM or ROM. Additionally, the ADAM hardware is designed so that memory can be accessed in 32K segments or "banks", which correspond to the lower 32K (addresses 0000H-7FFFH) and the upper 32K (addresses 8000H- FFFFH) of the memory space. Different physical memories, ROM and RAM, are assigned to either the low 32K or upper 32K, and these banks may be swapped in and out, mixed and matched, to make different 64K memory maps. Only one RAM or ROM may be active (i.e., directly visible to the Z80 microprocessor) in each low/high 32K bank at any one time. Here is a summary diagram of the various banks of ROM and RAM and what place they occupy in the 64K address space:

low 32K high 32K

0000H 2000H 6000H 8000H FFFFH

<-------------intrinsic RAM------------><----------intrinsic RAM----------> <-------------expansion RAM------------><----------expansion RAM---------->

                                        <----------cartridge ROM---------->

                        <----EOS ROM--->
                                        <----------expansion ROM---------->

Memory configuration is selected by writing certain values to dedicated hardware I/O ports; the exact details need not concern us here. The key idea is that you have a memory smorgasbord, and can choose one from column A and one from column B for the current active memory map. Note that when the OS-7 ROM is selected, there is also 24K of RAM included to fill out the low 32K. (This is the ColecoVision memory map.) Also, a note about memory expanders bigger than 64K: they are arranged as parallel 64K banks, with a separate bank select port which must be written to. (This is because XRAM greater than 64K is aftermarket and there was no existing Coleco standard.)

There are *two* default memory maps, depending upon which reset switch you pull to start your ADAM! If you pull the game reset, the memory map is:

low 32K high 32K

0000H 2000H 6000H 8000H FFFFH

<--OS-7 ROM--><-----intrinsic RAM------><----------cartridge ROM---------->

If you pull the computer reset switch, however, you get the following:

low 32K high 32K

0000H 2000H 6000H 8000H FFFFH

<------------SmartWriter ROM-----------><----------intrinsic RAM---------->

In each case, program execution begins at address 0000H, in whatever RAM or ROM happens to be switched in.

For a game reset, the code looks to see if a game cartridge is plugged in. If the "magic" identifier byte sequences AAH, 55H ("game", uses COLECOVISION title screen) or 55H, AAH ("test", skips the title screen) are found at 8000H- 8001H, a cartridge is present and the game code is executed (using the pointer at 800AH to find the start of game code). If not, the "TURN GAME OFF BEFORE INSERTING CARTRIDGE OR EXPANSION MODULE" message is displayed and the system halts.

For a computer reset, however, the boot code is far more complex (and interesting :-) ). Here's the sequence of events:

(1) Look for an expansion ROM (center slot; a "boot ROM" on one of the Micro Innovations I/O cards; *also* a "language card" French or German version of SmartWriter for European ADAMs). If found, jump to the program in it. There is a "magic" identifier byte sequence at 8000H-8001H of 66H, 99H which specifies a valid XROM; executable code begins at 8002H.

low 32K high 32K

0000H 2000H 6000H 8000H FFFFH

<------------SmartWriter ROM-----------><----------expansion ROM---------->

(2) If there is no XROM present, swap in the high 32K RAM bank:

low 32K high 32K

0000H 2000H 6000H 8000H FFFFH

<------------SmartWriter ROM-----------><----------intrinsic RAM---------->

(3) Then copy some code from the SmartWriter ROM to high 32K RAM and jump to it. This code then swaps in the EOS ROM and copies it to address E000H in RAM (where EOS usually resides).

low 32K high 32K

0000H 2000H 6000H 8000H FFFFH

                        <----EOS ROM---><----------intrinsic RAM---------->

(4) The EOS loader code then issues the _EOS_START function call and tries to boot a program from disk or tape. Part of _EOS_START switches to an all- RAM memory map, which is the default environment for user programs:

low 32K high 32K

0000H 2000H 6000H 8000H FFFFH

<-------------intrinsic RAM------------><----------intrinsic RAM---------->

(5) If no disk or tape is found, _EOS_START bails out to SmartWriter by issuing the _GOTO_WP function call, which swaps back in the SmartWriter ROM and jumps to the first byte of SmartWriter code at 0100H:

low 32K high 32K

0000H 2000H 6000H 8000H FFFFH

<------------SmartWriter ROM-----------><----------intrinsic RAM---------->

SmartWriter itself makes a number of bank switches (including to XRAM), but I will not describe them further at this time.

III. The Perils of Bank-Switching.

Bank-switching gives the ADAM its great flexibility. Indeed, that's how the ADAM is able to implement a complete ColecoVision as a subset of its own functionalities--swap in the OS-7 ROM plus 24K RAM, and the cartridge ROM, and run the game.

However, some care must be used. For instance, you'd better not swap out the bank of memory that your code is currently executing in! That is, if the current instruction is executing in the upper 32K of memory, you *cannot* swap out the upper 32K of memory--if you do, your code becomes invisible to the Z80 (you swapped it out), and execution proceeds at whatever the next address is in the new bank of memory. Since this is likely to be garbage, there's no telling what will happen; in any case, you'll have to reboot the computer to get control again. (The only exception is the carefully designed case in which two banks of memory contain exactly the same code in exactly the same place; in this case, while there is a switch from one copy to the other, the program itself stays in phase, and there is no loss of control.)

You must also keep track of what bank of memory the program stack is in. The stack is a special area of read/write memory which is used for temporary storage of data, typically as CPU registers (AF, BC, DE, HL, IX, IY, PC). Any machine code which does PUSHes or POPs is using the stack. The current entry on the stack is pointed to by the SP (Stack Pointer) register. If you swap out the memory bank which contains the stack, you must not try to POP (because there will be garbage at the current SP) or PUSH (because you'll overwrite whatever is in the new bank of RAM, possibly program code). Both errors have disastrous results. Trying to PUSH or otherwise write to memory that is occupied by ROM is futile, because ROM is read-only as far as the Z80 is concerned. If your code needs to use a stack, you may need to allocate a temporary stack in the same bank of RAM you're in, for use only during the bank switch; of course, you have to save the current position of the *old* SP and restore it when you're done bank-switching.

Interrupts are also a problem during bank-switching. If enabled, maskable interrupts cause an automatic jump to address 0038H; non-maskable interrupts, to address 0066H. Both of these locations are in the lower 32K of memory. For a typical RAM-based program which does not do any bank- switching, the programmer provides interrupt handler code which resides at those addresses in RAM (typically a jump to somewhere else). If the program swaps out the lower 32K of RAM, however, and interrupts are still enabled, there is a chance that an interrupt will occur while the RAM is swapped out. If there is not appropriate code at 0038H and/or 0066H in the *new* bank of memory to deal with the interrupt, whatever garbage is present at those addresses will be executed as if it were code, and control will be lost. A trickier case is provided by SmartWriter, which has hard-coded jumps to locations in EOS RAM (upper 32K). If for some reason the SmartWriter ROM is swapped in but a copy of EOS code isn't present in the upper 32K, or some other memory bank (like XROM or cartridge ROM) is swapped in, then the interrupt will cause a jump to garbage code.

IV. System Memory Maps.

Operating system code is like any other program code: it can be stored in RAM or ROM, and at any memory location which is convenient. The convention in both the EOS and CP/M operating systems is to put the operating system at the top of memory, leave the bottom 0000H-00FFH for interrupt vectors, and load user programs at address 0100H, extending upward in memory. Here's a diagram (turned on its side for convenience):

0000H 0100H FFFFH

<---cold start----><-------user---------> ... <-------operating---------> RST,INT, NMI program system

      vectors              code                           code

It is obvious from the above diagram that the maximum possible size of a (contiguous, non-bank-switched or non-overlayed) user program depends upon how big the operating system code is. For example, if the operating system code is 8K, then the user program has less than 56K of space available to it. In the case of EOS-5 (the default ROM version in every ADAM), the operating system occupies over 11K (8K for EOS code, data, and ADAMnet device control blocks, 2K for user file I/O buffers, 1K for system file I/O buffer, and 105 bytes for file control blocks). This leaves less than 53K for user programs.

How does a user program know where the top of its available memory is? This is very important for a program which needs every bit of available space for user-created objects, such as ADAMcalc (spreadsheets), SmartBASIC (programs), or SmartWriter (text files). Some operating systems provide a dedicated function call to find out what the highest available free address is. This lets a user program tailor its memory needs dynamically, based upon how much free space is available. This also allows future revisions of the operating system to get bigger and grow downward in memory, because it can then be expected that every program will call this top-of-memory function and adjust its memory usage accordingly.

Alas, EOS-5 has no such top-of-memory function call. (EOS-8 does, for the reasons described above.) EOS-5 is loaded from ROM to RAM address E000H, and 3K of file I/O buffers and 105 bytes of file control blocks are allocated below that. This is the de facto upper limit for user program memory. Even the EOS-7 rewrite, which has a default of 3 user file buffers (instead of 2), squeezes in the third file buffer and file control block under the old EOS-5 top-of-memory limit. (This was accomplished by wholesale rewriting and optimization for size of the EOS code, freeing up over 1K compared to EOS-5.) Thus, the otherwise pathetic Disk Manager program launching shell (which loaded EOS-7 from disk) could successfully run any existing Coleco software which assumed that it could have all memory up to the EOS-5 top-of-memory point.

V. Expanding EOS to Other Memory Spaces.

Given that all the Coleco software (and all of the SmartBASIC-based applications) is structured around this EOS-5 top-of-memory limit, and that reverse-engineering of binaries to source code for modification is a laborious task, it is thus an inescapable constraint that any future EOS revision which would run existing Coleco software *must* have an intrinsic RAM footprint no bigger than EOS-5. If EOS code and data overflow this limit, they will get clobbered by some application program which thinks it can use the space for itself.

Note carefully that I said "intrinsic RAM footprint", since that's where (with a few exceptions) all the Coleco software runs from--the base 64K of RAM. (Or in the case of SmartWriter, with the upper 32K of RAM, where EOS code is sitting.)

The EOS function calls are accessed via a jump table from FC30H-FD5EH in the upper 32K of intrinsic RAM. Thus, any program which makes EOS function calls must have the upper 32K of intrinsic RAM switched in at the time it makes the calls. When the function is completed, the memory map is the same as it was at the start of the call. What happens in between?

The answer is, *anything* can happen in between. Operating systems are supposed to be black boxes. There are defined entrances and defined exits, but what's inside the building itself is not defined, and indeed can be *anything* necessary to perform the requested functions. You can change the entire internal workings of the operating system, but if the defined entrances and exits are preserved, user programs shouldn't notice any difference. (This "black box" aspect of operating systems is what allows ADAMserve to substitute server disk drives and hard drive for genuine ADAM hardware--as long as _READ_BLOCK takes A=device number, BCDE=block number, HL=transfer address, and returns ZF=1 for okay, ZF=0 and A=error code for error, it doesn't matter where the block of data comes from, or what I have to do to get it.)

By extension, there is nothing that says that I have to stay with the current (entry) memory map while I'm performing an EOS function call. I should be able to switch to any memory configuration I want (subject to the Perils of Bank-Switching described above), as long as I put things back the way they were before I exit.

Thus, I should be able to put some of my operating system code into another memory space (e.g., XRAM), and with proper design and care, be able to transparently bank-switch in and out of that memory space, returning with the system memory map the same as it was at the start. I could fill an entire 64K of XRAM with EOS code, keeping only the jump table and the code necessary for bank-switching in intrinsic RAM. This way, user programs can keep their existing memory maps (i.e., they don't have to be reverse-engineered to source and patched to become dynamically-allocating), and EOS code can effectively be as big as it needs to be.

VI. The Need for Controlled Access to XRAM.

If some of EOS code is made resident in XRAM, then XRAM becomes an important shared resource. User programs are no longer free to appropriate XRAM for themselves without regard to what might be stored there already, and in use by the operating system. If the user program overwrites the EOS code or data, then the system is corrupted and will crash if the garbage code is executed, or garbage data is used.

How can you tell if XRAM is present? As noted above, cartridge ROM and XROM have "magic" identifier bytes at reserved locations which signify that a valid ROM is present. At system reset, XRAM is wiped and contains data of undefined value, so there are no "magic" identifiers. However, the presence or absence of XRAM can be determined experimentally, by simply writing some data to the XRAM memory space, then trying to read it back. If XRAM is present, you will be able to read back what you wrote; if XRAM is absent, you'll get random data when you try to read it back. Since the data are random, it's best to write to more than one memory location (on the odd chance that random noise might give you the byte you wrote), and with a definite pattern of bits in the bytes. Typically, the "magic" bytes AAH and 55H are used, because AAH = 10101010 binary and 55H = 01010101 binary (an alternating pattern of set and clear bits).

XRAM greater than 64K can also be detected using this method. After selecting an XRAM memory configuration, each parallel bank of 64K can be selected (using the appropriate bank select port) and tested. Typically, to avoid having to exhaustively test every possible bank (a 2 MB expander has 32 parallel banks of 64K each), advantage is taken of the fact that memory expanders exist only in a few sizes (64K, 128K, 256K, 512K, 1 MB, and 2 MB), and only the "critical" bank for each size need be tested to determine its presence. Starting from the bottom, look at banks 0, 1, 3, 7, 15, and 31; the highest one detected determines the size of the XRAM.

Note that the XRAM detect method described (i.e, writing "magic" data and trying to read it back) is *destructive*--if XRAM is present, whatever data was already there at the test addresses gets wiped out. It is a simple matter to make detection non-destructive, however, by just reading the test addresses first, then doing the test write/read, and finally writing back the original contents if the test was successful. Unfortunately, none of the XRAM detection routines I have seen in the software that I have disassembled (SmartWriter, ADAMcalc, SmartBASIC 2.0, File Manager, PowerPaint, Walters RAMdisk) use non-destructive XRAM testing. Sad to say, I didn't either in the special HARDDISK 2.3/3.9 with RAMdisk that I created in 1991 for Herman Mason and George Koczwara; and I don't think I altered Tony Morehen's code for the XRAM detect in ADAMserve File Manager, either (though the necessary changes are trivial given that I have the source code). For shame!

One thing that I *did* do, however, in the HARDDISK 2.3/3.9 with RAMdisk was make sure that my XRAM-resident RAMdisk code sat in places other than where the XRAM detect routine of File Manager was making its (destructive) test writes. The need for this was experimentally-determined, after I had laid out my XRAM memory map as seemed most straightforward to me, implemented the RAMdisk driver, and found it got clobbered by File Manager. I don't remember if I had any problems with SmartWriter or ADAMcalc; and the hard drive version of PowerPaint had been patched by me anyway to use the hard drive instead of XRAM, so the latter wasn't a problem.

In any case, I hope you clearly see the difficulty in trying to create a shared resource when there are existing programs which use it with abandon. The choices are to alter the programs (usually very hard) or avoid using part of the shared resource that the programs want to use for their own (ultimately very limiting).

There is a final "easy" way out for me as programmer, but not for you as user: Ignore the first 64K of XRAM completely, and put EOS into the second

64K of XRAM, utilizing the leftovers (and any higher banks of XRAM) for a RAMdisk. This avoids the Coleco software problem because the Coleco software doesn't know about any XRAM above the first 64K. This is a disingenous choice, however, because it requires at least 128K of XRAM. 64K expanders are common enough that I can assume everyone left as an active ADAMite either has one or can get one; not so for the larger expanders. It is easier to try to get people to have their SmartWriter ROMs upgraded than to expect them to get 128K and greater memory expanders.

VII. Synthesis.

Looking back to Zonker's injunction/plea to "K.I.S.S.", I'm not sure if he will perceive this article as "simple". I have tried to be more explicit in my reasoning, but there is some necessary complexity here, which I don't think has been treated as a coherent article within recent memory. (I'm sure there's some back issue of NIAD or the MTAG newsletter or Nibbles 'n' Bits somewhere which also covers this ground, maybe better or clearer than I have done here.) Putting my "K.I.S.S." hat on very tightly, here's a go at the TV Guide blurb for the last couple of issues of TWWMCA:

"I want to put more functionality into EOS. I can't fit it all into 8K of EOS RAM, and I *must* to avoid breaking existing programs. Technically, I can move some of EOS into XRAM, but there are potential conflicts with interrupts and other programs which already use XRAM. I can either make EOS work around the conflicts, or eliminate them by patching the programs. Both are hard problems. Since everybody uses SmartWriter at some point (if only because of an abort), and SmartWriter uses XRAM, SmartWriter must be patched in ROM to *not* use XRAM, if an XRAM- based EOS is to be stable."

As always, comments and questions are welcome.

VIII. Next Time.

Ron Mitchell's Ron'sWeek'n'ADAM for 5 October 1997 raises a number of interesting points about program design, style, and maintainability. I will devote next week's TWWMCA to a "Point-Counterpoint" discussion of his article.

See you next week!

*Rich*

***************************************************************************

Note: TWWMCA is archived. Back issues are available via anonymous ftp.

        ftp://junior.apk.net/pub/users/drushel/twwmca/

Files have the form wkyymmdd.txt, where yy=year, mm=month, dd=day.

***************************************************************************

Return to index

Article: rich13

by Richard F. Drushel (drushel@apk.net)

I. Prelude to Commentary on Ron'sWeek'n'ADAM 9710.05

As promised in last week's TWWMCA (9710.06), I will respond here to some interesting and important questions raised by Ron Mitchell in the 5 October 1997 installment of his article series, Ron'sWeek'n'ADAM. I will do this in USENET style, with quotes from Ron's article prefaced by >, and my commentary following. This is also known as "Point-Counterpoint" style, after the old segment on the CBS news magazine "60 Minutes" featuring opposing viewpoints by (I think) James Kilpatrick (a curmudgeon) and Shana Alexander (Bambi in the headlights of the oncoming truck). Unlike the originals (who inspired a parody on NBC's "Saturday Night Live" in which Dan Akroyd, in the Kilpatrick role, responded to Jane Curtin with "Jane, you ignorant slut!"),

I will not be mean or nasty. While Ron says, about his original article,
>There is gut reaction and there is, I think, more mellow
and considered comment.

I have no difficulty in looking past the "gut reaction" and recognizing the "mellow and considered comment".

The following analysis is intended to be objective. It may come across as cold-blooded and cruel, but that is a by-product of my desire to be objective, not from a desire to denigrate the work of others. I'm putting on my "scientist" writing hat here, so my own work is as much under the gun as anybody else's.

II. TDOS as an Example of Unmaintainable "Spaghetti Code".

A few TWWMCAs ago, in a survey of ADAM operating systems, I opinioned that TDOS (Tony's DOS, a CP/M-compatible operating system) in its current source code state is an unmaintainable mess of "spaghetti code", and that it would be better to start anew to build an ADAM-compatible CP/M than to make further use of the existing TDOS source code. To which Ron responded:

>The part about TDOS in Rich's work may indeed be accurate, but
the manner in which it is presented leaves the impression that TDOS co-authors Tony Morehen and Guy Cousineau somehow produced a product that was less than satisfactory. Having known these two talented men as friends for several years, I do not believe they wrote any 'spaghetti' code whatever. I believe that they wrote code that made sense to them, and I know that code con- tinues to perform yeoman service on several ADAM computers here. In fact, had it not been for TDOS, I would have dumped ADAM long ago.

I'm sure Ron knows this anyway, but I'll say it for the record: I am *not* knocking Tony Morehen and Guy Cousineau.
Both are skilled programmers whose works are still in active, productive use. The ADAM community would be much diminished were it not for their efforts. However, both Tony and Guy have moved on, leaving behind their programs for others (namely, me) to maintain. What does "maintain" mean? It means:

(1) fix any bugs that may be discovered; (2) modify to support additional hardware that may be

          invented;

          users; and

          (e.g., operating system patches) which may be required
          by applying (1)-(3) to the operating system itself.

All program maintenance requires adding or modifying program code. This may be done in two ways:

(1) modify the source (SmartBASIC, C, Pascal, Z80

          assembler) and recompile/reassemble to a new executable
          binary file; or

Modifying the source is the method of choice, because the source is typically written in a high-level language (like SmartBASIC) or, if in Z80 assembler, with useful variable names and subrou- tine names and some comments to explain how the program works. If all you have is a binary file, however, you must disassemble the binary to recreate a source file, then attempt to follow the program flow yourself (as if you were a Z80 CPU), and attempt to recreate and discover the thinking of the programmer. Even if you aren't doing a complete reverse-engineering of the program to source code (rather just disassembling what you think is the part you need to know about for a particular patch or bugfix), you have a difficult task--even with a "smart" disassembler tool like Kenneth Gielow's Z80DIS22 (which runs under CP/M). In any case, whether you have the original source or a reverse-engineered source, your task as maintainer of someone else's code is to be able to read the code well enough to know what it's doing, how it's doing it, and whether there are any important side effects, so that the changes you make to it (1) do what you intend, and (2) don't break anything else by accident.

This task is greatly influenced by the underlying organiza- tion of the original code. If the original code is well-organ- ized, hierarchical, modular, with related subroutines located close together, then it is easy to read. If, however, the code is cluttered, inconsistent, tricky (e.g., uses overlapping reading frames, self-modifying code, self-relocating code, over- lays, conditional assembly, or many disjoint source files), and jumps all over the place, then it is very difficult to read. If the original source lacks comments (text explanations of what the program is doing at a particular point, or overviews of its organization), then the source is little better than a disass- embly listing in terms of its readability.

The latter kind of code is the programming style referred to as "spaghetti", because like a plate of spaghetti noodles, it winds and twists and turns all around, with little hint of organization (and no comments or explanations from the programmer as to why it works or even what it's trying to do).

The TDOS source is such a "spaghetti" program, because

(1) its internals are mostly uncommented; (2) it has an "inline" versus "modular" design; (3) it has a confusing amount of conditional assembly; and (4) the source is broken up into a large number of files

          without an obvious organization.

III. Principles of Good Code Design.

Ron asks:

>1) [...By what standard is [spaghetti code] judged?

The answer is, by the people who have to maintain the code :-) Writing code in any assembly language is a difficult task,
and even the best-designed, best-commented code may be rather unintelligible to its author 6 months later. (This is absolute- ly true for me.) Anything which makes the code easier to understand, be it comments or helpful variable names, is a boon to the code maintainer (even if that is the original author).

>2) What activities are included in the process of managing or
maintaining source code, and why are they important, given that the product is out there and serving?

A program can be perfectly functional and easy-to-use from the end user standpoint, yet a nightmare of twisted "spaghetti" on the inside, completely hidden from the end user. If the end users are completely satisfied with the current operation of the program, and never demand either a change in its features or a change in its operating environment, then there is nothing to maintain, and the internal organization of the program is irrelevant. It is only when a maintainer is asked to fix a bug, or add a new feature, or ensure a backward compatibility, that the aims of the end user and the aims of the maintainer come into conflict. The first bugfix or hack or two can usually be made easily; but repeated patching upon patching results in a very "fragile" program--like a house of cards, the next card added may bring the entire structure down. And patches may have unforseen consequences which limit future patches.

>3) What is modular code, and why is having too many modular
source files a bad thing? After all, shouldn't we be carrying only the baggage that we need for a given appli- cation?

"Modular code" means that the code is organized into basic building blocks of functionality, and that unlike functions are not grouped together. The modules are often hierarchical, and higher-level functions are built up from calls to lower-level functions. Consider the following functional organization of the file system of ADAM's EOS operating system:

High-Level Functions:

	_MAKE_FILE         ;create a file
	_DELETE_FILE       ;delete a file
	_OPEN_FILE         ;open a file
	_READ_FILE         ;read from a file
	_WRITE_FILE        ;write to a file
	_CLOSE_FILE        ;close an open file
	_POSITION_FILE     ;move the read/write pointer in a file
	_RESET_FILE        ;reset the read/write pointer to the
			 beginning
	_TRIM_FILE         ;free up unused blocks at the end of a
			 file
	_QUERY_FILE        ;find a file without file type
	_FILE_QUERY        ;find a file with file type
	_FMGR_INIT         ;initialize the file control blocks
			 (FCBs)
	_INIT_TAPE_DIR     ;initialize the directory of a disk or
			 tape

Middle-Level Functions:

	_SCAN_FOR_FILE     ;see if a file exists
	_SET_FILE          ;update the directory entry for a file
	_CHECK_FCB         ;see if a FCB is in use (i.e., if a file
			 is open)
	_MODE_CHECK        ;see if an open file is open for
			 read/write/execution

High-Level Block I/O:

	_READ_BLOCK        ;read a block from disk or tape (with 3
			 retries)
	_WRITE_BLOCK       ;write a block to disk or tape (with 3
			 retries)

Low-Level Block I/O:

	_RD_1_BLOCK        ;read a block from disk or tape (no
			 retries)
	_WR_1_BLOCK        ;write a block to disk or tape (no
				 retries)

Low-Level Hardware I/O:

	_START_RD_1_BLOCK  ;ADAMnet: start reading a block
	_END_RD_1_BLOCK    ;ADAMnet: check if we're done reading a block
	_START_WR_1_BLOCK  ;ADAMnet: start writing a block
	_END_WR_1_BLOCK    ;ADAMnet: check if we're done writing a block
	_FIND_DCB          ;ADAMnet: find the device control block (DCB)
	_REQUEST_STATUS    ;ADAMnet: check the ADAMnet status of a device
	_SOFT_RES_DEV      ;ADAMnet: reset a device
	_READ_DEV_DEP_STAT ;ADAMnet: read device-dependent status

Note that higher levels provide more and more abstraction and insulation from the underlying hardware. This allows for porta- bility for programs which only use the high levels; the low levels can be replaced with driver code for totally-different, non-ADAMnet hardware, as long as the same parameter passing conventions are observed. For example, ADAMserve breaks into _RD_1_BLOCK and _WR_1_BLOCK to reroute requests for ADAMnet device I/O to server devices, if appropriate. (It also main- tains some dummy DCBs for the benefit of programs that try to read status data from ADAMnet directly by PEEKing at the DCBs.)

To return to TDOS, part of the reason that I cannot "easily" come up with an ADAMserve version of TDOS, even given the com- plete original source code, is that nowhere in TDOS is there the equivalent of _RD_1_BLOCK and _WR_1_BLOCK. Perhaps to save space or gain speed, TDOS talks directly to ADAMnet, without any layers of abstraction like _READ_BLOCK (for block devices like disks and tapes) or _READ_CHAR_DEV (for character devices like keyboards and printers). I have not been able to spare the time or mental effort to find a "safe" way to either add this layer of abstraction or branch around the direct ADAMnet I/O code. It is not impossible, just not as straightforward and guaranteed-to-be-foolproof as rerouting _RD_1_BLOCK and _WR_1_BLOCK in EOS.

These direct accesses to hardware are called "inline" program design, because the code isn't written as a subroutine which is CALLed; it's in the direct line of program flow. When optimizing a program for speed, inline design is the way to go, because you avoid the overhead of the CALL and the RETurn from the subroutine. If you must do the same thing at several different points in the program, however, you end up repeating the same bits of code over and over; thus, the pro- gram is larger than if you have a single subroutine which is CALLed whenever needed. Subroutines are a way to optimize a program for size, because the overall code takes fewer bytes of machine code.

The programmer must decide where to optimize for speed and where to optimize for size. Optimizing for size can create dense, tricky, unreadable code that exploits every possible side effect of each machine code instruction. This is where helpful comments that describe the intent of the code, perhaps even show it in a straightforward, unoptimized version, are invaluable to the code maintainer. Optimizing for speed is important for timing-dependent operations (such as reading characters from a serial port at high bitrate and storing them in a buffer). For instance, the code in the terminal mode of ADAMlink IValpha and V has a 1-byte subroutine call (RST) to the serial port read/ buffer routine about every 7 other instructions--the Orphanware and MI serial cards do not support interrupt-driven I/O, so the serial port must be polled at a fast rate in order to avoid losing characters at 19200 bps.

Ron comments:

>In all fairness, it could be noted here......
remarked (mused, lamented, complained) that TDOS was approach- ing the state where perhaps too many variations were 'out there' being used for one purpose and another. I think he realized that the 'monster' was growing. In my mind however, that in no way diminishes the immense utility of TDOS in this place here. Each of my ADAM systems has a different setup. I have boot disks for each variation. It is not a problem.

Again, end-user utility is not necessarily a function of the elegance (or not) of the internal organization of the program. As for having boot disks for each hardware setup variation, this is fine as long as either (1) someone has assembled a version of TDOS for your particular setup, or (2) you have the TDOS source yourself and you "roll your own" version as needed.

(2) is the typical situation for the general CP/M user these days; however, the TDOS source has *not* been released for gen- eral distribution. (I don't know if Dale Wick was "authorized" to let me have a copy, but that's where my copy came from.) In addition, the TDOS source is set up exclusively for the Z80ASM+ assembler from SLR, which, while an excellent and powerful assembler, (1) cost $150 when it was still available (I bought a copy at full price from Jay Sage at Sage Microsystems East), and (2) is no longer available now that SLR has sold out to Symantec. Porting the source to a different (freeware) assembler does not look to be an easy task. The upshot is that the average TDOS user does not have the means to create non- standard versions of TDOS for unusual hardware configurations, or novel configurations (such as ADAMserve).

IV. How Good Code Design Promotes Backward Compatibility.

Ron writes:

>Backward compatibility may be a problem for programmers, but
programmers need to keep in mind that some users cling tenaciously to what they're familiar with unless there is a erand and handsome payoff. Perhaps the payoff has not been adequately sold.

Believe me, as a would-be operating systems programmer, I understand that users like to keep the applications they already have, and are using very productively. But it's extremely frustrating to me to find programs that, for no "good" reason (i.e., no payoff in speed or ease of use or novel use of system resources), do "bad" things like bypass the operating system, write directly to the hardware, etc.

But Ron also asks:

>Why would a program written in the early and mid-eighties do
anything other than assume that it had the whole computer to itself? Was that not in fact true?

In the short-sighted short term, yes. However, even in the limited EOS operating system, there was some thought to what might come in future. The _READ_BLOCK and _WRITE_BLOCK functions take a 4-byte block number in the BC and DE registers; with 1K blocks, this is a maximum of 4 *gigabytes* of storage per block device. ADAMnet itself is a plug-and-play peripheral device net- work which modern Wintel systems have yet to achieve. And even though no communications protocol was ever defined, an ADAMnet device number (15) was reserved for a Gateway device which would have allowed ADAM-to-ADAM networking.

Some of these "hooks" for future expansion can be exploited today. Under ADAMserve, a 4GB ADAMnet hard drive could be creat- ed, or access provided to standard 650MB CD-ROMs--all because of support for "ridiculously high" block numbers in EOS-5. (Consider that tapes were 256K and original Coleco disk drives were 160K. Block 256 is B=1, C=0, D=0, E=0; a rather large "waste"!)

In the long term, however, the sloppy thinking that "the machine is *mine* and I can do what I want" is limiting. Part of the task of paving the way for future expansion is identify- ing all the "badly-behaved" programs and fixing them to be more considerate, when possible.

Ron says:
>When I hear this talk about so-called 'badly behaved programs'

I have to wonder 'badly behaved' for whom?

They are badly-behaved for those who would try to provide additional features in operating systems while maintaining the user-demanded "backward compatibility".

Ron:
>Speedywrite has often been cited as a fine example of a 'badly

behaved program' in the ADAM world. The fact that it provided superior wordprocessing capability to anything then available for EOS seemed to be completely irrelevant. Speedywrite provides it's own methods of dealing with the computer's re- sources and by doing so provided an impressive example - in my estimation - of what a creative imagination can do with limited computing resources if left unfettered by conventions and rules.

Yes--from the end user's perspective. And as long as that end user is content to use SpeedyWrite in its original environ- ment--taking over the entire machine, pull the reset switch when you're done--he has nothing to complain about. If he wants SpeedyWrite to run from a command line shell under an enhanced EOS which lives in XRAM, however, or can read files from a CD-ROM accessible by an ADAMserve connection, or can use an 80-column terminal, then he is (probably) out of luck, unless someone is willing to take SpeedyWrite to pieces and reassemble it in a "well-behaved" mode.

Ron:
>In my humble estimation, a program of Speedywrite's quality,
under any operating system, would be difficult replace.

And *that's* why, if there are too many "badly-behaved" legacy programs that end users want to keep using in their orig- inal form, then there is no point to trying to forge ahead with anything new and wonderful at the operating system level, because ultimately the result will be a nifty operating system which nobody will use but its author. I did that once with SmartBASIC 1.x; I don't wish to repeat the exercise.

Even Ron admits, after a laundry list of EOS's many shortcomings..........
>it's probably fairly safe to say that there's plenty wrong
with EOS about which plenty could be done. Whether or not it is worth doing except as an academic exercise remains debatable.

If the important applications that everybody wants to run had simply obeyed the injunction of the EOS programmers at the start of the EOS-6 code listing, it would have been soooo much easier to make enhancements to EOS:

          This absolute listing was generated to ease software
          development on the ADAM.  This listing provides the
          location of both released and unreleased entry points.
          Released entry points begin immediately in this file
          with the jump table and end before the first code
          segment listed.
          Released entry points include the jump table, common
          data areas (EOS_COMN), common data tables, and equates
          which describe the released data structures.  Direct
          access to code segments is STRONGLY DISCOURAGED and
          may make your application incompatible with some ADAMs.
          There is more than one version of EOS on the market
          at this time and updates are planned.

Much the same message is found at the beginning of the BIOS source code listing for the original IBM-PC (1983):

          THE BIOS ROUTINES ARE MEANT TO BE ACCESSED THROUGH
          SOFTWARE INTERRUPTS ONLY.  ANY ADDRESSES PRESENT IN
          THE LISTINGS ARE INCLUDED ONLY FOR COMPLETENESS,
          NOT FOR REFERENCE.  APPLICATIONS WHICH REFERENCE
          ABSOLUTE ADDRESSES WITHIN THE CODE SEGMENT
          VIOLATE THE STRUCTURE AND DESIGN OF BIOS.

And dealing with all the early MS-DOS applications which did *not* heed this injunction continues to cripple Wintel operat- ing systems development.

V. ADAM Hardware and Software Standards.

In closing, Ron has an excellent idea, which it's a pity that nobody had about 10 years ago:

>But perhaps we need something more. Perhaps we need not just a
standard, or specification covering EOS and how it will work. Perhaps we also need a standard for programmers proposing to develop new software. (I'm assuming there will be some; perhaps that's a leap of faith). At the very least we need some sort of common understanding as to how ADAM's resources are to be accessed.

Those few of us who are left as programmers and stewards of the programs of others pretty much know what the standards should have been, and what the crippling no-nos are. Short of a massive effort to reverse-engineer the top five EOS applications to com- plete, reassemblable source code (PowerPaint, ADAMcalc, Speedy- Write, SmartWriter, and ADAMlink V - I omit SmartBASIC and File Manager because I've already done them), there is no common base of "well-behaved" applications. *All* of the above 5 do bad things, or have bad internal organizations which make further (desired) expansion impossible. The ADAMserve version of File Manager (4.0, derived from a disassembly of 3.1) is now totally EOS-compliant; it does not bypass EOS to access hardware in any way at all. Its usage of XRAM buffers could be make RAMdisk-friendly without too much trouble, now that I have regenerated the source.

I can invent standards and promulgate/publish them through my TWWMCA articles; but unless part of my audience is ready to start writing some new applications (or willing to help reverse engineer some existing ones), it is really just vanity press...

VI. Conclusion.

On this note, Ron ends:

>'Nuff said. I do hope this discussion continues. I think it's
marvellous that Dr. Drushel has initiated some thinking about these things. I hope we can all follow along, contribute to the best of our ability, and learn in the process.

As I said at ADAMcon 08, I want to use my ADAM time and talents on a project which the remaining ADAM community deems to be of sufficient importance that it will actually *use it* if the project is completed, not simply ooh and ahh over it. Attaboys are *not* what I'm looking for. Frankly, I get a lot of intellectual pleasure in taking apart the sourceless binaries to see how they work, more so than trying to write user-friendly GUIs in Z80 asssembler :-)

See you next week!

*Rich*

Return to index

Article: rich20

by Richard F. Drushel (drushel@apk.net)

I. Status Report: SmartWriter Disassembly.

I'm happy to report that yesterday I finished my complete disassembly and reverse-engineering to assemblable source code of SmartWriter R80. This was done using Kenneth Gielow's Z80DIS 2.2 under the Z80MU CP/M emulator for MS-DOS. The new source is formatted for the Z80ASM+ assembler from SLR. The new source (minimally commented; it has all the EOS global symbols in it, as well as a few things I added on my own) is available for anonymous ftp at:

ftp://junior.apk.net/pub/users/drushel/sw_r80.zip

This file is a PKZIP 2.04g compressed version of the ASCII plaintext source. Note that it has no bugfixes or changes; it will exactly regenerate the original SmartWriter R80 binary, warts and all. Of course, now this source code can serve as the basis for bugfixes/upgrades to SmartWriter (including making it XRAM-friendly for a possible XRAM-based EOS).

II. Verifying the New Source Code.

How can I be sure that I correctly reverse-engineered the source code? The new SmartWriter source was verified in 2 ways:

(1) the new source was reassembled to a 32K binary image

          using Z80ASM+, then compared byte-by-byte with the
          original binary image of the R80 SmartWriter ROM.
          Except for padding out the unused ROM space
          with 00H instead of 0FFH, my new binary was identical
          to the old.

(2) the new source was modified by inserting a NOP

          instruction after the first instruction, reassembled
          to a binary image, then tested using Marcel de Kogel's
           ADAM Emulator for MS-DOS,ADAMEM.EXE.  The effect of
           the NOP is to displace all the code forward by one
           byte, without affecting the program operation (NOP
           means No Operation, it doesn't do anything).
           Extensive testing of the new binary revealed no
           operational errors.

What is the rationale for (2)? In the code, there are many references to ROM data areas (e.g., message strings, sprite patterns), which of course are to the addresses in ROM at which those data sit. In a typical program, executable code and non- executable data are intermingled in the binary image. Since a disassembler program doesn't know anything about the internal structure of the binary it's disassembling, data areas often appear as "garbage" machine code instructions in the raw disassembly output. It is the task of the human disassembler to recognize such "garbage" code and edit the listing to properly mark it as data. Any data references which aren't caught, however, will no longer point to the proper place if the code length changes in editing, and the data doesn't end up in exactly the same place in ROM that it originally occupied. Thus, insert- ing a NOP to shift the reading frame of the code, then testing the new binary for errors, will reveal any missing data references as program bugs.

The initial NOP-shifted binary did not boot at all--I got a black screen. Clearly, I had missed some data references. I then started from the end of the program and worked forward, inserting a NOP, reassembling, and then retesting. NOPs inserted towards the end allowed the binary to boot, but the screen was a bit scrambled. One bug at a time--track down what kept it from booting first, and worry about the screen garbage later.

By repeated NOP-shifting, always bisecting the interval between what would boot and what gave the black screen, I found the place in the code where I had missed a data reference. In the code which loaded EOS from ROM to high RAM, the start address of the ROM was listed as "program label 6000H" instead of just the number 6000H. Any NOP inserted after 6000H wouldn't cause a problem, but a NOP before 6000H would cause "program label 6000H" to have the *value* 6001H--which would cause the whole of EOS to be copied to the wrong location in RAM, and thus crash as soon as any EOS function call was attempted. Fixing this in the new source allowed SmartWriter to boot--but with a scrambled screen, as noted above.

The scrambled-screen problems were due to references to a few video RAM (VRAM) addresses which happened to have the same numeric value as some program labels. (The disassembler just sees the final number, and if there is a program label with that number, it substitutes that label name in the code.) During my initial cleanup of the raw disassembly listing, I had recognized and fixed a few of these anyway, from my familiarity with how VRAM is typically used; but some others less obvious slipped through the cracks. Again, it was repeated NOP- shifting (always bisecting the interval between a shift that "broke" the program and one which had no effect) which allowed me to zero in on the references to program labels which needed to be changed into numbers. (The strategy is exactly like that in the "higher-lower" game, in which one person thinks of a number, and a second person tries to guess it, the first person answering only "higher" or "lower" depending upon the accuracy of the guesses.)

When the screen was unscrambled, there remained a small glitch: in the ADAM'S ELECTRONIC TYPEWRITER mode, the message
string for SmartKey V was off by a few letters if I NOP-shifted the code at the beginning. Using the same procedure described above, I zeroed in on the offending part of the code, but couldn't see what was causing the problem: the critical address was the very address of the particular SmartKey V message string!

To make a long story short, the problem was that I had not correctly separated code from data areas in the subroutine which draws the SmartKey menus for the ELECTRONIC TYPEWRITER. In SmartWriter, SmartKey menus are drawn using an economical yet uncongenial-to-disassembly subroutine which includes the address of the string directly after the CALL to the menu-drawing routine. Here's the critical bit of code, correctly resolved:

C.0B07:

      CALL  DRAW_YELLOW_SK_4
;
      DW    I$12FC
;     -----------------
;
      CALL  DRAW_SK_5
;
      DW    I$132D
;     -----------------
;
      CALL  DRAW_SK_6
;
      DW    I$131C
;     -----------------
;
      RET
;
;     -----------------

;[...]

I$12FC:

      DB    ' ADAM''S ',0DH                ;0DH is carriage

      DB    ' ELECTRONIC TYPEWRITER',03H   ;03H is ETX,

      DB    ' MARGIN',0DH

      DB    ' RELEASE',03H

      DB    ' MARGIN/',0DH
      DB    'TAB/ETC',03H

The subroutines of the form CALL DRAW_YELLOW_SK_x draw a yellow box from SmartKey I to SmartKey x, with the text of string at the address following the CALL printed in black. The subrout- ines of the form CALL DRAW_SK_x draw a blue (2 possible shades, depending upon which SmartKey) box in SmartKey x's space, with the text of the string at the address following the CALL printed in white. The DW LABEL$ assembly directive means to store a Data Word containing the address of the program label LABEL$, whatever value LABEL$ has at assembly time.

The first time through the disassembler, however, all these "inline" data references get treated as code. When I first recognized the existence of the DRAW_YELLOW_SK_x and DRAW_SK_x family of functions, I searched through the code listing and (supposedly) changed all the "garbage" code to DW references. In the case of the 'MARGIN/TAB/ETC' string, however, I missed one; and the (2DH, 13H) was treated as the following assembly code:

      CALL  DRAW_SK_5
;
      DEC  L                ;2DH
      INC  DE               ;13H

This meant that, when I NOP-shifted the program anywhere prior to I$132D, the new value of this label was *not* updated in what should have been the data reference after the CALL DRAW_SK_5. The result was that this DRAW_SK_5 would *always* try to draw a SmartKey with whatever data it found at address 132DH, even if the actual message string had shifted to a different absolute address. Needless to say, putting in the correct reference as DW I$132D fixed the problem; and now I could edit the new SmartWriter source at will, without fear of such frameshift errors being introduced by the edits.

III. Code Fossil: ADAMlink Modem I/O in SmartWriter.

My first disassembly of SmartWriter was done in 1992 or thereabouts, using the UNASMHEX disassembler I wrote for Smart- BASIC 1.0 and 1.x (and ported to Microsoft BASIC). This disassembler did not make any attempt to generate assemblable source code; but I used it extensively, and it was my primary tool for figuring out how to patch PowerPaint for hard drives, HARDDISK 2.3 and 3.9 for RAMdisks, and ADAMlink IValpha to make ADAMlink V (not to mention SmartBASIC 1.0 itself to make SmartBASIC 1.x). I made a quick pass through SmartWriter just for fun, I guess, and at that time had discovered a truly amazing code fossil: SmartWriter knows about the ADAMlink modem, and tries to talk to it at startup!

I believe that I wrote a brief report of this discovery for A.N.N., but I can't be completely sure. At any rate, during the resourcing of SmartWriter, I came across the code again; so here it is, with some brief explanations:

MODEM_CTRL_PORT EQU 5EH ;ADAMlink modem control port (2651 UART) MODEM_DATA_PORT EQU 5FH ;ADAMlink modem data port (2651 UART)

;     -----------------

;Load a program through ADAMlink modem!
;At least that's the intent.  It can't work, however, because
;there is no handshaking for any of the data reads; a 300 bps
;modem can't supply the characters that fast.  Maybe if the
;proper handshaking were added...it would be interesting.

C$103C:

      LD    BC,(D$1071)
      LD    A,B
      OUT   (C),A               ;send first init command
      LD    BC,(D$1073)
      LD    A,B
      OUT   (C),A               ;send second init command

      LD    A,(D$1075)
      LD    C,A                 ;get data port
      IN    A,(C)               ;read for first magic number
      CP    0AAH                ;was it magic1?
      JP    NZ,J.1070           ;no, so exit
;
      IN    A,(C)               ;yes, so read second magic number
      CP    55H                 ;was it magic2?
      JP    NZ,J.1070           ;no, so exit

;
      IN    E,(C)               ;yes, so get DE=count
      IN    D,(C)
      IN    L,(C)               ;get HL=load address
      IN    H,(C)
      PUSH  HL                  ;save start vector

      IN    A,(C)               ;read a byte
      LD    (HL),A              ;save it
      INC   HL                  ;point to next address
      DEC   DE                  ;one less count
      LD    A,E

      OR    D                   ;is D=E=0?
      JR    NZ,J$1065           ;no, so keep going 'til done
;
      POP   HL                  ;yes, so restore load address
      JP    (HL)                ;and jump to program start
;
;     -----------------

      RET                       ;exit
;
;     -----------------

;initialization data for ADAMlink modem

D$1071:

      DB    MODEM_CTRL_PORT,00H     ;port, data

      DB    MODEM_CTRL_PORT,80H     ;port, data

      DB    MODEM_DATA_PORT         ;port
;     -----------------

As noted in the code comments, there's no way that this can work with the ADAMlink modem as we now have it; there's no hand- shaking for any of the modem data port reads. So, if you try to set this up now, with a second computer ready to send a program at 300 bps, it will fail. Now that I have reassemblable source for SmartWriter, though, it might be worth trying to make this code workable, just for kicks.

Why is this routine in here, to load and run a file over the ADAMlink modem? At this late date, only the SmartWriter program- mers themselves could answer definitively; but I will offer this intriguing speculation as food for thought:

What if Coleco planned to start a nationwide BBS service, like CompuServe? They would have support areas for the ColecoVision and the ADAM, news about upcoming hardware and software, etc. Presumably the only way you could login would be via an ADAMlink modem (there were no third-party ADAMlink modems or serial interface boards to use standard Hayes-type modems). What if you wanted to try out a demo version of some new ColecoVision game or ADAM program, while you were on-line? In the appropriate forum, you could issue a command to start downloading a program (after making sure that your ADAMlink boot tape or disk was out of the drive), then pull the reset switch on your ADAM. Since you're still on-line, and loader code in SmartWriter doesn't hang up the phone, you could start receiving the file. This loader would grab the file, put it in RAM at the appropriate place, then run it. Presumably, the demo program would have a software escape mechanism to reboot the machine under ADAMlink so you could continue your online session. And this would be "safe" for Coleco because there would be no way for the users to save the program they had downloaded, because it wasn't downloaded to disk or tape, but rather directly to RAM, from which there is no escape (the ADAM not having a built-in debugger or program tracer).

In many respects, the Coleco ADAM is to the 1980s what TV-based "network computers" are to the 1990s. Technically, however, there is no way that 300 bps could have efficiently transmitted multimedia-type data. Even a 4K demo program would take over 2 minutes to download at 300 bps 8N1. I predict that "network computers" will be as commercially successful as the ADAM...

IV. Possible Repair of SmartWriter R80 Bugs.

Now that SmartWriter can be changed at the source level (meaning, repairs are easy and can be as extensive as desired), you should all send me your lists of long-standing bugs to fix. The one that I remember is the inability to access disk 2 (drive D). I know where in the code the tape/disk detects are, and it looks to be a straightforward fix to add support for disk 2. (I may even start playinmething to do with there being an extra linefeed or half-linefeed at the bottom of pages during printing; if someone can send me a detailed description of how to produce this bug, I'd be grateful).

From the PRINT menu, there is an unused SmartKey menu entry for PRINT FILE. Making it print A-type (plain ASCII) files is trivial; making it interpret an existing SmartWriter file without actually loading it in and printing it from the workspace is probably a lot harder, but doable (I haven't looked).

Also, it might be nice to have native support for the PIA2-type parallel printer card (instead of having to run FAST- PATCH or some equivalent). Again, adding the driver code is easy--and I've even published the core parallel printer driver in a previous TWWMCA. Of course, anything requiring specific escape codes for parallel printers is out. A 132-column mode would probably involve deciphering and documenting SmartWriter's RAM data tables above 8000H, which I haven't done and wouldn't particularly relish doing.

It is also very easy to disable the XRAM detect routine, which would prevent SmartWriter from recognizing XRAM at all, thus making it more friendly to future XRAM-based operating system upgrades. If disk 2 support is being added, it probably would be worth adding RAMdisk (device 26) support at the EOS level (leaving it to the EOS RAMdisk driver to worry about how to manage the different memory bank switches that would be necessary).

So, send me your bug lists for SmartWriter! There are more than 3751 bytes free at the end of the 32K ROM to play with, which is lots of space in Z80 machine code!

See you next week!

*Rich*

*****************************************************************

Return to index

Article: ron_1

October 5, 1997

by Ron Mitchell

A somewhat schizophrenic article follows. There is gut reaction and there is, I think, more mellow and considered comment.

Hopefully you'll be able to tell the difference, and hopefully you'll accept it in the spirt in which it is offered, constructive comment. It is not my intent to poke jabs at anyone.

I've been reading Richard Drushel's (drushel@apk.net) late August and September contributions. He has invited public comment on a number of issues.

I have to confess that an understanding of Richard's material requires me to reach to a fair depth into my bag of hobbyist computer experience. Even then, I have more questions than answers about what he describes.

In the comment which follows, I'm going to spend some time asking those questions. Some of the answers I may already know, but some I want to hear again. In some cases I'm having trouble with verbiage, technical jargon, and programmer concepts that I'm only vaguely familiar with. My perspective has always been and remains that of a user. Perhaps I'm a slightly more experienced user than most, but having read what Richard has written over the past month, I certainly know that I'm not a programmer.

The history on various ADAM operating systems, presented in outline, was most informative, but in one place infuriating. Every time I hear an adverse comment about TDOS, I get mad, not just mildly annoyed, but eye-flashing, neck-straining, lip trembling, fist-shaking angry. (Just ask Ron Collins.)

The part about TDOS in Rich's work may indeed be accurate, but the manner in which it is presented leaves the impression that TDOS co-authors Tony Morehen and Guy Cousineau somehow produced a product that was less than satisfactory. Having known these two talented men as friends for several years, I do not believe they wrote any 'spaghetti' code whatever. I believe that they wrote code that made sense to them, and I know that code continues to perform yeoman service on several ADAM computers here. In fact, had it not been for TDOS, I would have dumped ADAM long ago.

All of which leads to my first three questions:

1) What is spaghetti code, and by what standard is it judged?

2) What activities are included in the process of managing or maintaining source code, and why are they important, given that the product is out there and serving?

3) What is modular code, and why is having too many modular source files a bad thing? After all, shouldn't we be carrying only the baggage that we need for a given application?

Backward Compatibility for the Backward:

Yup. From me a programmer gets user inertia of the finest grade. I don't care how 'nifty' a new version of 'anything' is if I have a 'thing' that does the job I want done, a 'thing' that I'm familiar with and fits me like an old slipper.

Backward compatibility may be a problem for programmers, but programmers need to keep in mind that some users cling tenaciously to what they're familiar with unless there is a grand and handsome payoff. Perhaps the payoff has not been adequately sold.

Question 4

Why would a program written in the early and mid-eighties do anything other than assume that it had the whole computer to itself? Was that not in fact true? Given the limited memory available, was there really any legitimate possibility of multi- tasking? I know that Radio Shack had OS9 which claimed to be almost UNIX-like in its multitasking capabilty, and that there was GEOS in the Commodore 64/128 world which could share data amongst its applications, but beyond that was there really a computer capable of doing more than one thing at a time? When I hear this talk about so-called 'badly behaved programs' I have to wonder 'badly behaved' for whom?

Speedywrite has often been cited as a fine example of a 'badly behaved program' in the ADAM world. The fact that it provided superior wordprocessing capability to anything then available for EOS seemed to be completely irrelevant. Speedywrite provides it's own methods of dealing with the computer's resources and by doing so provided an impressive example - in my estimation - of what a creative imagination can do with limited computing resources if left unfettered by conventions and rules. And that, in my opinion was and is to author David White's credit. In my humble estimation, a program of Speedywrite's quality, under any operating system, would be difficult to replace.

The Ultimate Failure of SmartBASIC 1.x

Quote: "The ultimate failure of SmartBASIC 1.x was that it could
not directly run existing SmartBASIC programs which were full of PEEK's, POKESs, and CALLS."

Comment: Seems to me that another reason it didn't catch on was

         that users didn't understand the payoff that it offered.
         At the time it arrived here, it would not correctly
         address my Hazeltine terminal, a problem which the
         author subsequently corrected, and it was competing for
         my time and attention with GODOS. Both required me to
         learn new commands, and it seemed to me at the time
         that GODOS offered 'sexier' possibilities such as mixed
         font sizes on the screen, dialogue boxes and pulldown
         menus. As things eventually played out, I had difficul-
         ty remembering anything other than accepted SmartBASIC
         commands and the DBASEII programming language. Nothing
         else would stick for some unfathomable reason. Hence,
         little got done here with either SmartBASIC 1.x or
         GODOS.     One user hangup clarified for the record.

...................I'm wandering.

Moving along to the real point of all this.... which is , I hope, to be helpful.

I would not have known about any of EOS's shortcomings unless I had become a CP/M and TDOS user, and an owner of all sorts of other computers designed at roughly the same time as ADAM. So following is my 'spaghetti user' perception of what's troubling EOS. Bear in mind that I'm talking about what you can do under EOS without any other program loaded. In ADAM's case, such a state is hypothetical because you've never seen the bare bones EOS, unadorned without Smartwriter, SmartBASIC, CP/M, TDOS, or an application of some sort. Presumably it's there, but we have to accept that on faith, in much the same manner as a Commodore 64 user accepts his or her bootup state. At any rate, I will mark EOS down because:

1) It cannot format a blank disk without the aid of an appropriate program;

I can do that with my Apple II and IIe. I can do it with the C64 and C128, albeit from BASIC which is included on startup and therefore counts as available. I can do it with any CP/M machine such as the Osborne, albeit with a transient.

2) As Rich Drushel has already pointed out, there is non- standard use of certain resources such as the memory expander. Having said that, if I were asked to prepare a user specification on the use of the memory expander, I have absolutely no idea what I would recommend. There are times when I want a RAM DISK. There are times when I want additional I/O buffer space. There are times when I want contiguous transient program area. At no time, do I ever want a print spooler, that much I'm sure of, but then, who knows!.

Suffice it to note that there is non-standard use.

3) There is no inline-assembler or debug utility. Even the simplest of boot monitor programs such as that for the Xerox 820-II provided at least an elementary capability in this regard.

4) Machine language is required to access some of the computers functions, such as sound and VRAM operations.

5) EOS performs no memory management. As I understand it one of the duties of any good operating system is to fulfill the role of 'traffic cop' so that if more than one application is in memory, each receives its fair shair of CPU attention.

6) EOS provides no file maintenance capability, such as copying, renaming, or deleting files.

7) EOS provides no visible file organization capability such as that available under TDOS with named directories.

8) EOS provides no command-line-history buffer. In fact there is no place for command-lines at all.

9) There is no capability to generate a report on memory status stating what memory is used, and what is clear and available. In other words, where can I load just one more "Terminate and Stay Resident" program without crucifying something important already in memory?

10) Under EOS files of operating system commands such as .BAT or .SUB files are not supported.

Leaving the list at that, it's probably fairly safe to say that there's plenty wrong with EOS about which plenty could be done. Whether or not it is worth doing except as an academic exercise remains debatable.

I for one would like to see the effort proceed, because I think that it will result in some interesting possibilities. I like the concept of a user shell that Rich Drushel refers to in his August 31 article. I like the concept of having high level commands to access system resources, provided that the commands are short and to the point. (Things like "WriteWindowAT x,y" don't cut it.)

Insofar as providing additional memory is concerned, I can see no problem with setting aside a 64k memory expander as a hardware requirement for the new operating system. Seems like a small price to pay.

But perhaps we need something more. Perhaps we need not just a standard, or specification covering EOS and how it will work. Perhaps we also need a standard for programmers proposing to develop new software. (I'm assuming there will be some; perhaps that's a leap of faith). At the very least we need some sort of common understanding as to how ADAM's resources are to be accessed. For example, if it's a 'no-no' for me to make direct BIOS calls, then perhaps someone had better tell me why. Perhaps we also need a common understanding about how programs are to be judged or reviewed. And perhaps we need a way of defining user specifications describing in layman's terms the job that any given piece of software is to do.

In plain fact, we need standards and procedures that even the good people at Microsoft, Corel, Digital and Lotus have had difficulty in establishing. The possibility of competitive advantage shouldn't be a problem with us, but it has been elsewhere, and it certainly was in the days when new ADAM software was being written.

'Nuff said. I do hope this discussion continues. I think it's marvelous that Dr. Drushel has initiated some thinking about these things. I hope we can all follow along, contribute to the best of our ability, and learn in the process.

Return to index

Article: ron_2

Ron:
Well, I'm not absolutely certain, but I think there are ways to get around that with judicious use of .REL files. CP/M 3.0, I believe, does a better job.

Geoff:
>I would say that TDOS lives up to all of it's promises. However
it might be nice to have an operating system that supports, for example, TSRs (which TDOS doesn't), and modular device drivers instead of having a kernel that is patched for this thing or that). Simply put, spaghetti code means code that is cobbled together without a plan, or patched too much, or code that makes no sense to anyone but its author. There are a variety of explanations, but I think these three are the most common.

Ron:
Sounds like a pretty tall order to me. It assumes that everyone is on the same wave length, and if they're all on the same wave- length, then chances are their creativity has gone down the tube to some extent at least.

The programs I had most fun writing were the ones that were cobbled together without a plan. To me "plan" is a 4 letter word. But you're absolutely right of course.

Geoff:
2) What activities are included in the process of managing or maintaining source code, and why are they important, given that the product is out there and serving?

The most common way of doing this is to heavily comment the source code so that some other person can understand how it works. This is especially helpful if trying to write a program for an operating system. Other ways my programming teachers taught me were Flowcharting and Pseudocode

Ron:
Yup. Sometimes the problem here is that people are too close to their work, and fail to understand that the comments might not make sense to somebody who wasn't there at the time the code was written. Comments of necessity have to be short and to the point. The shorter they get, the greater the liklihood of them being misinterpreted.

Geoff:
Well, modular code is something you can add bits to and remove (i.e. device drivers) without having to recompile that piece of software. For example, you can't remove hard disk support from TDOS unless you install an entirely different revision of TDOS. I think this could be extremely helpful. The other is a common set of routines that are used by several programs (like sound or graphics routines). The problem with this approach becomes painfully obvious for anyone that tries to compile a program in UNIX or a UNIX variant (like Linux or FreeBSD or Solaris, etc.) when you try to compile something that you don't have all the pieces for. The compiler can crap out for no appar- ent reason at all. This happened several times to me when trying to compile ADAMEM until I realized I was trying to compile with ZLIB support (zlib allows you to run "crunched" software without having to "uncrunch", it does this automatically), and I didn't have ZLIB installed. I don't think this type of radical modular approach is terribly practical for the ADAM, simply because the ADAM isn't a very large platform.

Ron:
Understood, thanks. At the time ADAM software was actively being written,there was precious little co-operation between developers on anything. I don't think it would have been possible then to reach any sort of common understanding on the way resources were used. And users didn't understand enough about software available to exercise any kind of buying pressure on the developer commun- ity. Bad scene all around.

Geoff:
I think a certain degree of backward compatibility is important. However if something new comes along with more potential and bet- ter comes along, who really cares if program 'X' when a perfectly suitable replacement exists that will work? After all, we're using a computer which is a dead platform...why not play with it a bit?

Ron:
Agreed. Besides I have four of them. Once can stay 'traditional', and that would answer the problem of backward compatibility. Most of us have more than one these days.

Geoff:
Insofar as providing additional memory is concerned, I can see no problem with setting aside a 64k memory expander as a hardware requirement for the new operating system. Seems like a small price to pay. I thought you were a staunch believer in backward compatibility? What about all those people who don't have memory expanders? Seriously, I'm just poking at you. :)

Ron:
Well yes, but I want my cake and eat it too. :)

Geoff:
Amen...perhaps we'll never see another version of EOS come along. If so, why do we have to use the jump table at all for accessing BIOS routines?

Ron:
Exactly. This is what was given to me as the reason for NOT making direct BIOS calls. What is your program going to do if the location of that routine changes with a new version of the OS? But if, as you say, there is no new version of the OS, what's the problem.... other than it countenances bad programm- ing habits which might get you in trouble on another platform.

****************************************************************

Appreciate the comments Geoff. Thanks.

Ron Mitchell

Last page. Enter command or <CR> to continue !

Return to index

Article: ron1021

I suppose the job at hand is pretty much standard no matter what the programming language:

- Define the problem to be solved.

- Understand all aspects of the problem, including what it is and what it is not. Be able to state the problem or task concisely.

- Break the problem or task down into as many component parts as possible, and write a plain language solution to as many of the components as possible

The solution will include:

- input of data - processing of data - output of data

It also helps to understand a thing or two about the users who will be relying on the program for a solution to their problem, which is hopefully the same as the one the programmer is attempting to solve.

If the programmer can write about what he or she is doing at every step of the process, that too will assist everyone in understanding the solution, provided of course that the writing is clear and concise, and provided that the programmer can step back about 600 miles from the work so as to see it in sharper perspective, warts and all. I read all this in a book somewhere along with some rather interesting generalizations about users.

1) Users hate computers.

2) Given a choice between the right key and the wrong key, the user will press the wrong one. If the program fails to live, then it's dead.

3) The more educated the user, the greater the liklihood of user data being saved to the program disk.

4) A user will never read a doc file if there is some faint hope of getting the job done without it.

5) If a program doesn't work, the user will blame the program before looking in a mirror.

6) It is always a user's perrogative to criticize a program without knowing anything about it.

And while we're on the subject of generalizations, here are a few more, gleaned simply by looking around my own 'snake pit' at the collector's pieces duly assembled, or disassembled as the case may be.

1) They all have a screen of some sort that has to be controlled, formatted, made to look pretty and readable, and filled with some sort of communication. They all have defined ways of doing various screen functions, such as clearing, cursor positioning, color or mode changing, etc.

2) They all have a keyboard with somebody's fingers attached - usually mine.

3) They all have a way of presenting printed information. Some share, but all can do it. This type of output must also be formatted and made to look businesslike and professional.

4) Each has some method or other of storing information - even the Timex/Sinclair. Information, data, programs that are stored must also be retrievable to be of any use. When they're retrieved, something must be done with them.

5) Some have ways of communicating with eachother and with the outside world, and software designed for that purpose. They do this in ways that can be understood from one computer to the next make or age notwithstanding.

6) All have ways of producing sound just to spice things up, and keep the user interested.

7) All have modes where graphics are possible, again to spice things up and keep the user awake.

We could go on and on. I'm sure I've missed something. Never- theless it seems, given this sort of setting, that the program- mer's task is one of solving the problem at hand in a manner of greatest benefit to the greatest number of users. In doing so, the resulting software will probably:

- declare quantities and structures needed to start, and

       assign preliminary values or weights to whatever variables
       are appropriate under the circumstances

- introduce the purpose of the program along with instruct-

       ions if needed

- set up a manner of working with the user that makes sense

- ask the user to input some data, fly a plane, shoot a gun,

       kill an alien, or access a file of aliens previously shot,
       open a channel to some other point, or load a game that
       was already in progress

- process any new information that arrives from whatever

       source, be it disk, keyboard, modem or tape, according
       to whatever recipe or or algorithm is given for the task

- present some sort of output on the screen, on the printer,

       on a computer 12000 miles away, or on the machine half
       naked out on my workbench.

- ask the user if there is any more to do and proceed

       accordingly

- or... end things off in some sort of acceptable manner

      short of a complete crash. Usually this includes restoring
      the machine state to what it was before program loading.

Again, I've probably forgotten something. The user can fill in the blanks. The user will understand.......

Return to index

Article: ron15oct

October 15, 1997

Rich Drushel's response to my last weeks article provided satisfying answers and comment. It's true; no man is an island, although sometimes I wish it wasn't so. It brings to mind an anecdote that was sufficient to convince me that I might be better off finding another hobby. I have not written a serious line of code since this particular experience, not because I didn't want to, but for reasons I'll get to in a moment.

First some background.

In the early days of Ottawa's ADAM User Friendly Group prior to 1987 when there was enough membership dues income to pay for a regular meeting hall, Guy Cousineau and I used to pull this "good-hacker, bad-hacker" routine. It was pretty well always unrehearsed and completely spontaneous, and it went something like this:

In my role as newsletter editor, President, Chief-Mover-and- Shaker, and frequently lone contributor, I would publish short SmartBASIC routines in each month's issue of our bi-monthly rag. Sometimes they were a little longer than short, sometimes they ran 5 pages. The intent was to have members type these listings into their ADAMs thusly adding to their software library and their programming knowledge. Some of us continued to believe that one of the most effective tools in a study of programming is the study of other peoples' work, both good and bad.

It was also our intent to spawn our own programming expertise by encouraging other members to write programs for publication. For a while there was a fair stock of material, some good some bad, but all of it instructive in one way or another. I used to write a fair number of these 'home cooked' programs myself for use in the newsletter and as programming examples. The process of causing the computer to do something I had thought up in the shower was both challenging and satisfying.

On occasion, Guy would cite an example of poor programming (practice good hacker) in one of my programs already published. I would put on my 'grim-horrible-person' expression (bad hacker) and slink off into the corner while Guy straightened us out. It provided good meeting content.

In 1987 or thereabouts, one such program drew comment from a completely unexpected source. A young lad about 15 had joined us. He relied on me for rides to meetings since we lived in the same part of town. One night on the way in to an AUFG meeting, we were talking about my latest game, ADAM Wars II. It was a re-write of something Barry Wilson had distributed earlier, and at one point it actually made the NIAD PD list. At any rate, to make a long story even longer, I was having trouble with a mysterious "Stack Overflow Error" in one particular portion of this program. It did all sorts of things including re-write 5 characters of the VDP character set to provide some box line elements I wanted, including it's own not very professional looking smartkey routines, and a variety of other tasks assoc- iated with generation of a pair of random values for dice, mov- ing a player piece around a game board, and on and on. The end product worked well enough that I actually earned $25. from NIAD in payments. When the "Stack Overflow" thing was happening, I gave copies of the program listing to a couple of people including the young member I was driving to meetings. He was into computer science at the high school level and volunteered to look at my program.

That was the first time I ever heard the word 'spaghetti' used in reference to programming; not just any programming, my programming. Out of the mouths of babes! I hurt easily and I do not suffer well. For those of you who don't know, by the way, a "Stack Overflow Error" can be generated by the Smart- BASIC interpreter under circumstances where it can't figure out where to return following the execution of a subroutine. If you've written spaghetti, you've probably left yourself wide open to a situation where you jump around within a called subroutine to the point where you forget where you were supposed to return to when the subroutine eventually ends. Clear as mud? A POP statement might fix things up and a total re-write with a properly planned flow chart might do even better. As mentioned earlier, I haven't written a line since. My method was the 'code-now-plan-later-fly-by-the-buttseat' school of computer programming. It was a method that suited my purposes at the time. I certainly did have a whole pile of fun playing about, and I discovered a whole pile of informa- tion about what wouldn't work. Those were the good old days.

Return to index

Article: subscrib

			ANN SUBSCRIPTIONS

***************************************************************

This is another in a long line of monthly offerings from the ADAM NEWS NETWORK, A.N.N. for short. Subcription rates are $25.00 US per year and insure you that a disk will be delivered to your door each and every month all year long. The monthly disk is also available on CompuServe in the CLUB section (GO CLUB) at Library 9 and Library 10, but you will incur down- load charges from CompuServe and you will need to know how to use some basic TDOS or EOS programs in order to make readable versions of the disk each month. The choice is yours.

To subscribe and have it delivered to you, sent $25.00 US and of course your complete mailing address to our treasurer:

Bob Bair 6552 N 400th E Kendallville, IN 46755 The monthly disk is available in any format you need; 160k, 320k, 720k or digital data pack. All available upon request.

Bob Slopsema Editor-in-chief

Return to index

Article: will

Subject: OS, GUI and why Adam shouldn't be a doorstop.

Warning: This message is a first draft compilation of my thoughts
about Adam over the last couple of months. It's quite a tome.

Let me state first off that I'm coming to this a a relative neophyte. Adam was my first computer, taught me a lot about assembly and it led me to a varied career writing bbses, games and the first "multi-media" apps. Now I write a lot of (trivial, actually) perl and Visual Basic code. The upside is this has allowed me to purchase Rich Lefko's entire Adam collection. This is a LARGE collection of hardware, software and documentation, over 500 pieces and over 200 pounds of stuff. Now we know that I actually have a monentary investment in my words. You'll have to take my word for it that I have the intellectual interest. Just to clear up any questions about the sincerity and serious- ness of my words. (LOONNGG WIND!)

At this point I feel, difficulties (well understood) aside, that the Adam can be made a platform useful to those that wish to use it (me for one). It would certainly be a trivial effort compared to the MAME project. MAME, for those who haven't seen it is an emulator that, with it's next release will emulate over 240 classic arcade games. This with about 80 programmers working on 5 CPU emulators, 3 or 4 Sound chip emulators, and a myriad of video and memory hardware.

Certainly with the (2-4?) programmers that can be rounded up here, we can create a new, open architecture? Let me give a vague outline of my ideas. Much of this will echo comments made by Richard and others on this list. Suffice to say I will gladly incorporate any good suggestion into my (personal) Adam-schaung. These thoughts are nebulous at best and somewhat un-organized but I believe complete.

A brief overview: Disk/Tape loadable. No ROM dependancy. Maximum compatibility with legacy OSes. Extensible. If I want to go out and create an IDE hard drive interface card, I should be able to write a driver that works seamlessly with the new OS and provides maximum backwards compatibility to those legacy OSes. An integrated, high-level language that allows full OS & assembly access. A GUI.

Compatability: People want to run their special widget and we just need to lump it. How can we overcome the problems? Well, if the problem is truly with *ONLY* a very few apps/games, we can modify them. But what about CMP apps, TDOS? What we need is for a new OS to branch, as transparently as possible to legacy OSes. Making use of whatever "autorun" facilities are available. Where we can't get a quick solution, I'm content to let there remain a ragged adge. Negative Stimulous will do a lot to get people to upgrade their apps. The OS should _NEEDS_ to be load- able from any media. Disk, tape, ?!? 90% of users won't up- grade their ROM chips. It should be based on a core which fits within the code 8k EOS RAM, but extensible though disk-loadable libraries and devices. Media Compatibility: The OS should provide low to mid level routines for CPM, EOS and any other formats that can be squeezed in.

Programmability. Also provided should be a high-level language, It should allow inline assembly, and provide easy, high-level access to all layers of the OS. it should, ideally, be a compiled language with an IDE.

GUI: WE don't need to write a GUI that's a lame imitation of Windows. That defeats the purpose of providind a new _Adam_ OS. But while exploiting the Adam's strengths, most noteably Smart- Keys and users' familiarity with them, a GUI should provide 'modern' enhancements, like Cut, Copy and Paste for Programs working "Within" the OS/GUI.

How? I think, and I'm open to being proven wrong, that this whole structure can be supported on very small headers, 2-6 bytes. say, roughly in psuedo code:

	Library {
	   name : BYTE  ; 255 libraries
	   Size : WORD  ; Libraries up to 65k
	   Functions : Array of LibraryFunction
	}

	LibraryFunction {
	   UniqueID : BYTE
	   NextFunction : BYTE ; (as an offset)
	   FunctionCode: BYTE[254]
	}

Problems here are obvious. All libs would require routines to be limited to 256 bytes, and there are library management prob- lems, but these can be worked out.

Code Maintenance: If any one comes after us to maintain this platform, Code maint can be made trivial. Good documentation for the OS and associated apps, and a distributed repository of mirrored nformation. Also, I think the "GNU" approach of source code availability can be encouraged through the copyright license and the above repository.

Build the OS in a layered way, maybe:

	     USER APP           <- Top level
	-------------------
	       GUI
	-------------------
	   Extended OS
	-------------------
	Libraries & Devices
	-------------------
	 Disk Loaded "EOS"
	-------------------
	     ROM EOS            <- Bottom Level

I've got the programming skill to significantly contribute to such a project, but not the Hard knowledge. I'll get a great deal of that from the docs coming with my system. But not enough. While Richard Certainly doesn't want hurrahs (he deserves them from what I've seen), He plays currently a very important role as the guru of the Adam community. I'd like to ask him to try and write a ground up tutorial on the Adam Hard- ware for the mailing list . I'm willing to provide all the Web space needed, and all the web apps, such as a Message forum, and code-repository for the project, and LOTS of my own time and effort.

Again, feel free to criticize and question. This kind of project will require everone's input. Also I apologize in advance for mis-spellings and grammatical errors. This was typed WAY too late at night.

Return to index

Article: will3

Ron Mitchell wrote:
> Now you've got some stuff to chew on haven't you. :)
I know that equipment will be as productive in your hands as it was in Rich Lefko's. Rich was for a very long time a writer of ADAM newsletter articles, and an expert on most topics to do with the ADAM. I know it! I went ahead and had Rich send all his newsletters, etc! I've already gotten a couple small "hello world" programs written. whew, long time since I've done alot of assembly...

> I just have one small suggestion Will, and I hope you'll take
it in the spirit in which it is offered. As mentioned earlier, you need a strong and lasting line of communication with Rich Drushel. Our world is what it is today, with problems that Rich Drushel has already discussed, because in earlier times people failed to work together. There was too much emphasis on competitive advantage and oneupmanship. We don't have any room for that now.

I agree. I didn't want to come off that way. I am the newbie in this, and it's plainly obvious that Richard is "The man." Maybe in couple years I'll actually have some standing to _argue_ over a point of Adam programming. So far all I've been trying to do is spew out my 1/2 cent. So, Richard, if I came off as being pushy, or whatever, I apologize. No offense meant.

> 'Nuff Said.
> By the way, did you get the C Compiler package I sent?

Got the Compiler. I'm waiting to get it transfered over to Adam media. My problem right now is that _all_ the 5-1/4" drives I had laying around (1 1.2 meg, 2 360K) are busted. So I'm probably going to modem transfer them. That'll take a long time at 1200bps..

Here's a question: Is there a way to get a PC to write 720K 3-1/2" Adam media? I've got one on the system, but can't read them. Urgh, probably have to write some kind of transfer program. I've got alot of work ahead. I've gotten through Volume 1 of Mel Ostler's excellent "Hacker's Helper" series and have started on Vol.2. Great books!

Return to index

Article: will4

Does any kind person here have a good description of Adam disk formats/filesystems. I'm especially interested in 3-1/2" disk info(720K) 22disk is just not working. All the 360K disk drives I've tried in my machine come up with "Not Ready" errors. So I want to look at maybe writing a good translation util..

Or maybe I'll just have to go to Adamserve.

Will

Return to index

Article: willn

Subject: ACK! I'm in Adam Heaven.

Well folks, I just today received Rich Lefko's Adam collection.

AIHAYYAHIYAA!

I've got a room full of ADAM stuff! There's so much stuff here it'll take me a year to digest it all! I'm in 7th heaven. I want to publicly thank Rich, This stuff got here exactly 13 years TO THE DAY I got my first Adam. My Birthday, 1984.

OOOHHH. Well, In a while, I'll have a nice list on my website.

Just wrote to say KEWL!

Editor note: now this is ONE happy ADAM owner. Of late there have been more than just Will who have expressed an interest or at least a mostalgic look back at the ADAM. Apparently, the interest is still there if not the motivation. Now, HOW do we go about getting them interested enough to come back aboard the fun computer?????? The first and maybe the best way is to exchange e-mail whenever the oportunity presents itself and encourage them to take action on their interest in ADAM.

Return to index

Article: xmaspics

Apparently I FORGOT to inform you all on the need to make a Power Paint picture for this years annual XMAS card on the December disk of the ADAM NEWS NETWORK. The picture needs to be the most original, funny, serious or otherwise imaginative you can think up for the greeting to the ADAM community. Formats can be varied in either SmartPaint (.HRP), PowerPaint 10k binary or 80k work space. Also, feel free to submit a couple for Ron to mull thru, and also and interesting christmas sound files you might have just laying around doing nothing. These sould be in "general MIDI standard" format with a .MID extension.

Submit pics, music to Ron Mitchell @ : 70323,2267 on CompuServe, or the Internet @ : ronaldm@mars.ark.com

OR Ron.Mitchell@access.crcn.net OR you may mail them direct to Ron @ : Ron Mitchell 2075 Cooke Ave Comox, British Columbia, Canada V9M 1Y5 OR mail them to me and I will send them on to him.

I know this only gives you a few weeks to draw up some pictures, but take a stab at it for a night or two and send them in!

Editor..........if I don't get fired <g>

Return to index

Article: zonker

At 11:11 PM 10/6/97 -0400, you wrote:
>Looking back to Zonker's injunction/plea to "K.I.S.S.", I'm
not sure if he will perceive this article as "simple".

No, not precisely "simple" but a much better job of explanation then i have ever had before. this may be due to the fact that i asked a question direct, within context of an online conversa- tion rather that, say, reading a sol swift article in nibbles and bits. this does NOT demean one iota the effort you put forth to explain. while the terms are still pretty "high end", you took some time to define some terms and put them in context. i appreciate that.

But now i wonder....this seems like an awfull lot of work with very little return. that is, if you count that "return" as number of adam users who will actually USE this system. i know that we are way beyond the point of any commercial viability. and i'm quite certain your mind doesn't work that way anyway. if this is a task that you wish to tackle because it is something that YOU want to do, then i say go to it. if it can somehow be "sold" (not in the dollars and cents sense <sorry about that!>) to the adam users at large that would be all to the better.

i'm not convinced that this is something that i myself can embrace.... -zonker

Return to index

Article: zonker2

To: "Ron Mitchell" <ronaldm@mars.ark.com>
From: (zonker) Bart Lynch
Subject: Re: Hard Drive Version of Swifts

At 04:18 PM 10/16/97 -0700, you wrote:
>Does anyone have a version of Sol Swift's Personal Calendar
Utility and Label Workshop programs that runs on a mini-wini or IDE hard drive? If so, could I beg, borrow, steal or otherwise appropriate - Ron Mitchell

i haven;'t heard of such a critter, ron. you might yell at gene welch....it's a sure bet that if he has the program, he's loaded it into his hard drive.

Editor note:..........food for thought, anybody know of it??

Return to index

Return to adamcon.org | Adam News Index | Volume 97