.ADPIE DOS (cid:0) (cid:0) (cid:0) (cid:0) (cid:0) (cid:0) (cid:0) (cid:0) (cid:0) (cid:0) and Pieler Lechner (cid:0) (cid:0) SOFTWJlRE Fourth Printing. May t982 By Don Worth and Pieter Lechner A product of xi aUJlUTY SOFTWJlRE 6660 Reseda Blvd., Suile 105 'L 1 1 I '1 Reseda, CA 91335 I .N .. Fachhochschulbibliofhek Niederrheio Abt. Mond ng!odbach DISCLAIMER Qualily Sollware shall haye no liability or re5ponslbilily \0 Ihe r , purchaser or any olher person or entity Wilh respect to any liabili'y, loss or damage caused or alleged to be caused directly or indireclly I by Ihis manual or lis use, Including bot not hmlled to any Interru!>" , lion in service, loss 01 business and anticipatory protils or consequenllal damages rHulling Irom lhe use 01 this product. I • COPYRIGHT <>1981 BY QUALITY SOFTWARE I This manual is published and copyrighted by Quality Sollware. All rights are reserved by Quality Sollware. COPYing, duplicating. seiling or otherwise distribUling this producl IS hereby expressly lOfbklden except by prior wnllen consent 01 Quality Sollwar• . The word APPLE and the Apple logo are regIstered trademarkS 01 APPLE COMPUTER, INC. APPLE COMPUTER, INC. was not in any way Involved In the Willing or Olner preparation 01 this manual, nor were the lacls j)fetented here reviewed lor accuracy by that company. Use oltha hum APPLE shOuld not be construed 10 represen' any endor ..... mt)(It, olll(lal Of" otherwise, by APPLE COMPUTER. INC. TABLE OF CONTENTS INTRODUCTION Chapter 1 THE EVOLUTION OF DOS Chapter 2 0053 OOS 31 OOS 3.2 DOS 3.2 1 DOS 3.3 DISKETTE FORMATTING Chapter 3 TRACKS ANO SECTORS TRACK FORMATTING DATA FIELD ENCODING SECTOA INTERLEAVING DISKETTE ORGANIZATION Chapter 4 OISKETTE SPAce ALLOCATION THE VToe Us THE CATALOG 0 J\ THE TRACK/SECTOR LIST TEXT FilES BINARY FILES APPlESOFT AND INTEGEA FILES OTHER FILE TYPES EMERGENCY REPAIRS Chapter 5 THE STRUCTURE OF DOS OOS MEMORY USE THE OOS VECTORS IN PAGE 3 WHAT HAPPENS DURING BOOTING Ch.p'''. USING DOS FROM ASSEMBLY LANGUAGE OlReCT USE OF THE DISK DRIVE CALLING AEAOIWRITE TRACK/SECTOR IAWTS) AWTS lOB BY CALL TYPE CALLING THE OOS FILE MANAGER FilE MANAGER PARAMETEA LIST BY CALL TYPE THE FILE MANAGER WORK AREA COMMON ALGOAITHMS TABLE OF CONTENTS ChOp'O,7 CUSTOMIZING DOS SLAVE VS. MASTER PATCHING AVOIOING RELOAD OF LANGUAGE CARO INSERTING A PROGRAM BETWEEN OOS AND ITS BUFFERS 8AUN OR EXEC A HELLO FILE REMOVING THE PAUSE DURING A LONG CATALOG Chop"'S DOS PROGRAM LOGIC CONTROLLER CARD ROM - BOOT 0 FIRST RAM BOOTSTRAP LOADER - BOOT 1 OOS 3.3 MAIN ROUTINES OOS FILE MANAGER REAOIWRITE TAACK/seCTOR OOS ZERO PAGE USE Append'. A EXAMPLE PROGRAMS TRACK DUMP PROGRAM DISK UPDATE PROGRAM REFORMAT A SINGLE TRACK PROGRAM FINO TAACK/SECTOR liSTS PROGRAM BINARY TO TEXT FILE CONVERT PROGRAM Append' •• DISK PROTECTION SCHEMES Append'. C GLOSSARY Indell ACKNOWLEDGEMENTS Th,nks go to ViC Tolomei IOf his ,",Slance in di'Me,lng D05 3 I.oct to lou Rlyas'Of hili pllient proofreading Thlnkl liso 10 my wlle Carley lor pulling up wilh the cllICkely clack 01 my Diablo long Into the nlghl. Don 0 Wor1h TNinks to !he people It Computer'and 01 Sooth Bay (CAlhlornl') wM lent me syppot'l bOth ollheirlime and equIpment. arid speci.1 th.nk,loJohn 00111.1$0. whoseencour.gement helped me to complete Ihe 'ask BAG OF TRICkS .3. ... A Supet' DI" UtNlty by the Authors oj 8_.th (cid:0) (cid:0) (cid:0)OOS 1/ you linG BENEATH APPlE OOS 1.1"'1.11, you iIoI'IOuIO allo find BAG OF TRICKS an Impo,,.nl help In ...m lnlng .nd (cid:0) (cid:0) (cid:0) (cid:0) (cid:0) (cid:0) (cid:0) (cid:0)up ";'OUr di. ..." ". BAG OF TRICKS I, I package ollouf mlehlno (cid:0) (cid:0) (cid:0) (cid:0) (cid:0) (cid:0) (cid:0) (cid:0).",brO\lllntt wh!eh go I., beyond thl ....m pte prOOf.tnt In AppendiI A 01 tl'ris tIOOII. Ute< frleOOly and _II aocurMntld. (cid:0) (cid:0) (cid:0) (cid:0)dl'k (cid:0)(cid:0) (cid:0)(cid:0)(cid:0)(cid:0)(cid:0)(cid:0) (cid:0)'-undoubtedly the besl one ,w"Jlble'or m. Apple II, (cid:0) (cid:0) (cid:0) (cid:0) (cid:0) (cid:0) (cid:0)" !he low prIc. (cid:0) (cid:0) (cid:0) (cid:0) (cid:0) (cid:0) The 1000f prog,.ml and thel, lunelions .ra: I TRAX durnjM .nd ..." ". .... "'11' !tICk. -'1!let t l-MeIOf Of .8-Mc:IOf. dltpllp tne Inter".! Apple d,p.". !Otll'lllthng InfOfll'lllllOtl, .....:j ". exception' to , ..n OIIrd formalS 2 ,I!N\eITm .... ,11 ,.IOtIl'lllI one Ot fIlOI" tr.cU on dl ....n ., ... hile Inempling to Pf_ Iny atl on Both 13-MeIOt Ind l6-MelOt IOtm,1S 1'1 Iuppoflld Mo,. 3. ZAP pro¥idn IhtI buIc capabihly to f'IIId. (cid:0) (cid:0) (cid:0)(cid:0)Ind uPCIIII di,kln. MeIOfi thin 50 eomtnllldt _ IVI,lebie 10 ...." IIIe u_ In Ioc:Iting. COInpII"ng, Ind chlngitlg tnedl" Of! the d,1io;1'I11 Prinler IUppofl. 100. You won'I "-lieve now mlny UMlul OPIioM ZAP ha, .. flllCAT lutomttMth, P'o(;M,ol 'eeo. ... 'ng.d.mIlgldClI.logtrlC. TII.ditloetl.etnOfo (cid:0) (cid:0) (cid:0) (cid:0) (cid:0) (cid:0) (cid:0)lOt trac. HCtor h. ... theEnn ,",,,.. UHf can .uIgn.".me to """ound Irf flllCA and '"lOtI IhenIIO the CI"1og ClI. .. mIIy be , ..t OtId In tllll ... ..,.. II you hive _ "-d • ditlo c,ull, you know ... h.\. good dilk (cid:0) (cid:0)(cid:0)(cid:0)(cid:0)(cid:0)(cid:0)II wortll. e.gln,.,.,. ... ,11 .pprecilot. tile "hind-hOldIng" IUIOtIaII Ihll ... 11I.u,.1 him In repairing hll CllmII!JId di. ..." H • .....:j trtl ."panenc.ct .......... 11 .ppreelol'- now lut (cid:0) (cid:0) INtily ne can perIorm .f'I.Ilpll and r.palfl BAG Of TAICI<S ,eq ... J'M I .81< Apple II Ot Appl. \I Plu •. 1 CHAPTER INTRODUCTION i)cne!'th Apple OOS is intended to serve as a companion to A.pple's DOS Manual, providing additional information for the advanced programmer or the novice Apple user who wants to know more about the structure of diskettes. It is not the Intent of this manual to replace the documentation provided bV Apple COlllputer Inc. Although, for the sake of continuity. some of the material covered in the Apple manual I. also covered here, it will be assumed that the reader is re.aonably familiar with the contents of the DOS Manual. Since all chapters presented here may not be of use to each Apple owner, each has been written to stand on its own. The information presented here is a result of intensive disassembly and annotation of various versions of DOS by the authors and by other experienced systems programmers. It also draws from application notes , articles, and discussions with knowledgeable people. This manual was not prepared with the assistance of Apple Computer Inc. Although no guarantee can be made concerning the accuracy of the Information presented here, all of the material included in o neath Apple DOS has been thoroughly researched and tested. There were several reasons for writing Beneath Apple DOS: TO show direct assembly language access to DOS. To help you to fix clobbered diskettes. TO correct crrors and omissions in the Apple documentation. TO allow you to customize DOS to fit your needs. TO provide complete information on diskette formatting . I NI., WUE SEVEMl fIfAS(ljS (cid:0) (cid:0)(cid:0) (cid:0) (cid:0) (cid:0) (cid:0) (cid:0) "BENEATH API'lE (cid:0) (cid:0) (cid:0) (cid:0) (cid:0) .(cid:0)... ,-, When Apple Computer Inc. introduced its Disk Operating System (DOS) version 3 in 1978 to support the new DISK II drive, very little documentation was provided. Later, when DOS 3.2 was released, a 178 page instructional and reference manual became available covering the use of DOS from BASIC in depth and even touched upon some of the internal working' of DOS. With the advent of DOS 3.3, the old 3.2 manual waa updated but the body of information in it remained essentially intact. Beyond these Apple manuala, there have been no significant additions to the documentation on DOS, apart from a few articles in APPLE user group magazines and newsletters. This manual takes up where the Disk Operating System Manual leaves off . Throughout this manual, discussion centers primarily on DOS version 3.3. The reasons for this are that 3.3 was the most recent release of DOS at the time of this writing and that it differs less from DOS 3.2 than one would imagine. Wherever there is a major difference belween the various DOS releases in a given topic, each release •• 11 be covered. In addition to the DOS dependent information provided, many of the discussions also apply to other operating systems on the Apple II and Apple III . For example, disk formatting at the track and sector level is, for the most part, the same. 14 2 CHAPTER THE EVOLUTION OF DOS Since its introduction, Apple OOS has gone through three major versions. All of these versions look very much the same on the surface. All commands supported by 005 3.3 are a180 supported in 3.2 and 3,1. The need for additional versions has been more to fix errors in DOS and to make .tnor enhancements than to provide additional functionality . Only DOS 3.3 has offered any major improvement in function; an increase in the number of sectOrs that will fit on a track from 13 to 16. DOS 3 • 2t June 1978 I DOS 3.1 - 20 July 1978 , The first release of DOS was apparently a victim of a rush 1 at Apple to introduce the DISK II. As such, it had a number of bugs. With the movement towards the APPLE II PLUS and the introduction of the AUTOSTART ROM, a new release was needed. DOS 3.2 • 16 Febru.ry 1979 Although OOS 3.2 embodied more changes from its predecessor than any other release of OOS, 9o, of the basic structure of OOS 3.1 was retained. The major differences between DOS 3.1 and 3.2 and later versions of OOS are listed below: - NOMON C,I,O is the initial default under DOS 3.2. MON C,I,O was the default under DOS 3.1. - Input prompts (>,1,*) are echoed when MON 0 is in effect, not under MON I as was the case under 3.1. - When a DOS command was entered from the keyboard, OOS executed it and then passed a blank followed by a carriage return to BASIC under 3.1. Under 3.2 only a carriage return is passed. - Under 3.2, certain commands may not be entered from the keyboard but may only be used within a BASIC program (READ, WRITE, POSITION, OPEN, APPEND). Under 3.2, when LOADing an APPLESOFT program, DOS automatically converts from APPLESOFT ROM format to APPLESOFT RAM format if the RAM version of BASIC is in use and vice versa. - DOS 3.1 could not read lower case characters from a text file; DOS 3.2 can. ,-, - Some OOS co. .a nds are allowed to create a new file, other. will not. Under OOS 3.1, any reference to a file that didn't exist, caused it to be created. This forced OOS 3.1 to then delete it if a new file was not desired. (LOAD XYZ under 3.1 if XYZ did not exist, created XYZ, deleted XYZ, and then printed the file not found error message.) Under 3.2, OPEN is allowed to create a file if one does not exist , but LOAD may not. - Under 3.1, exiting to the IDOnitor required that the MOnitor status register location ($48) be set to zero before reentering OOS. Under DOS 3.2 this is no longer nece •• ary. - The Read/Write-Track/Sector (RWTS) section of DOS disable. interrupts while it is executing. Under 3.1, RWTS could be interrupted by a peripheral while writing to a disk, destroying the disk. - The default for the 8 (byte offset) keyword ts 0 under 3.2. - DOS was reassembled for 3.2 causing most of it. interesting locations and routines to move slightly. This played havoc with user programs and utilities which had DOS addressea built into them. - Additional file types (beyond T, I, A, and B) are defined within DOS J.2, although no commands yet support the • . Th. new types are S, R, a new A, and a new B. R has aubsequently been used by the DOS TOOLKIT for relocatable object .odule assembler files . At present, no other uae ia aade of these extra file types. - Support was added under 3.2 for the AUTOSTART ROM. - All tilea open when a diak full condition occurs are closed by DOS 3.2. - As with each new release of DOS, several new programs were added to the I114ster diskette for 3.2. Among these was UPDATE 3.2, a replacement for MASTER CREATE, the utility for creating master diskettea. UPDATE 3.2 converta a alave into a ..a ter and allowa the HELLO file to be renamed. 001 3.2.1 • 31 July 1171 OOS 3.2.1 vas essentially a -maintenance cele• •• - of DOS 3.2. Minoc patches were ..d e to RWTS and the COPY progr •• to correct a timing problem when a dual drive copy was don •• Additional delaya vere added folloving a switch between drivea. 2-2 DOS 3.3 - 25 AugUll1t1C1 Introduced in mid 1980 as a hardware/software upqrade from OOS ).2.1, the OOS 3.) package includes new bootstrap and .tate ROM chips for the disk controller card which provide the capability to format, read, and write a diskette with 16 'ectors. (These ROMs are the same ones used with the I.ANCUAGE SYSTEM.) This improvement represents almost a 25' Inc rease in available disk space over the old 13 sector rorMat. Also included in the ).) package is an updated version of the OOS manual, a BASICS diskette (for 13 sector boots) , and a master diskette. Although the RWTS portion of OOS was almost totally rewritten, the rest of 005 was not reassembled and only received a few patches: - The initial 005 bootstrap loader was moved to $800 under 3.1. It was at $)00 under 3.2. In addition, as stored on I the diskette (track 0 sector 0) it is nibbilized in the • . ame way as all other sectors under ).1 . - A bug in APPEND which caused it to position improperly if I the file was a multiple of 256 bytes long was fixed under • ) .1 . I - A VERIFY command is internally executed after every SAVE or BSAVE under 1.1. - All • bytes are used in the Volume Table Of Contents (VTOC) free sector bit map when keeping track of free sectors. This allows 005 to handle up to )2 sectors per track. Of course, RWTS will only handle 16 sectors due to hardware limitations. If a LANGUAGE CARD is present, OOS stores a zero on it at $EOOO during bootstrap to force the HELLO program on the master diskette to reload BASIC. OOS is read into memory from the top down (backwards) under 3.3 rather than the bottom up. Its image is st ill stored in the same order on the'diskette (tracks 0, I, and 2) , however. Additional programs added to the master diskette under 3.3 include FlO, a generalized file utility which allows individual files or groups of files to be copied, MUFFIN, a conversion copy routine to allow 3.2 files to be moved to 16 sector 3.3 diskettes, BOOT 11, a program which will boot a 13 sector diskette, and a new COpy program which will also support single drive copies. Under 3.2, speed differences in BOrne drives prevented their use together with the OOS COpy program. Because the COpy program was rewritten under 1.3, that restriction no longer applies. 2-3