ProDOS 8 Technical Reference ManualTheProDOS8TechnicalReferenceManualisidenticalincontenttothepreviously publishedProDOSTechnicalReferenceManual. InformationinthismanualcoversProDOS8through1.1.1.Fordetails onchangestomorerecentversions,seeProDOSTechnicalNote#23.

Contents

FiguresandTables ...xiii Preface ...xv AboutProDOS ...xv AboutThisManual ...xvi WhatTheseMean ...xvii AbouttheAppleIIc ...xvii Chapter1 Introduction...1 WhatIsProDOS?...2 1.1 1.1.1 UseofDiskDrives...3 1.1.2 VolumeandFileCharacteristics...5 1.1.3 UseofMemory...5 1.1.4 UseofInterruptDrivenDevices...6 1.1.5 UseofOtherDevices...6 Summary...7 1.2 Chapter2 FileUse...9 UsingFiles...10 2.1 2.1.1 Pathnames...10 2.1.2 CreatingFiles...13 2.1.3 OpeningFiles...13 2.1.4 TheEOFandMARK...14 2.1.5 ReadingandWritingFiles...15 2.1.6 ClosingandFlushingFiles...16 2.1.7 FileLevels...17

Pagevi

FileOrganization...17 2.2

DirectoryFilesandStandardFiles...17 2.2.1 2.2.2 FileStructure...18 2.2.3 SparseFiles...20

Chapter3 MemoryUse...21 LoadingSequence...22 3.1 VolumeSearchOrder...23 3.2 MemoryMap...23 3.3 3.3.1 ZeroPage...25 3.3.2 TheSystemGlobalPage...25 3.3.3 TheSystemBitMap...25 Chapter4 CallstotheMLI...27 TheMachineLanguageInterface...28 4.1 IssuingaCalltotheMLI...29 4.2 4.2.1 ParameterLists...31 4.2.2 TheProDOSMachineLanguageExerciser...31 TheMLICalls...32 4.3 4.3.1 HousekeepingCalls...32 4.3.2 FilingCalls...33 4.3.3 SystemCalls...35

Pagevii

HousekeepingCalls...36 4.4 4.4.1 CREATE($C0)...36 4.4.2 DESTROY($C1)...40 4.4.3 RENAME($C2)...42 4.4.4 SET_FILE_INFO($C3)...43 4.4.5 GET_FILE_INFO($C4)...47 4.4.6 ON_LINE($C5)...51 4.4.7 SET_PREFIX($C6)...54 4.4.8 GET_PREFIX($C7)...55 FilingCalls...56 4.5 4.5.1 OPEN($C8)...56 4.5.2 NEWLINE($C9)...58 4.5.3 READ($CA)...59 4.5.4 WRITE($CB)...61 4.5.5 CLOSE($CC)...63 4.5.6 FLUSH($CD)...64 4.5.7 SET_MARK($CE)...65 4.5.8 GET_MARK($CF)...66 4.5.9 SET_EOF($D0)...67 4.5.10 GET_EOF($D1)...68

4.5.11 SET_BUF($D2)...69 4.5.12 GET_BUF($D3)...70 SystemCalls...71 4.6 4.6.1 GET_TIME($82)...71 4.6.2 ALLOC_INTERRUPT($40)...72 4.6.3 DEALLOC_INTERRUPT($41)...73 DirectDiskAccessCommands...73 4.7 4.7.1 READ_BLOCK($80)...74 4.7.2 WRITE_BLOCK($81)...75 MLIErrorCodes...77 4.8

Pageviii Chapter5 WritingaProDOSSystemProgram...81 SystemProgramRequirements...82 5.1 5.1.1 PlacementinMemory...82 5.1.2 RelocatingtheCode...84 5.1.3 UpdatingtheSystemGlobalPage...84 5.1.4 TheSystemBitMap...84 5.1.4.1 UsingtheBitMap...85 5.1.5 SwitchingSystemPrograms...86 5.1.5.1 StartingSystemPrograms...86 5.1.5.2 QuittingSystemPrograms...87 ManagingSystemResources...89 5.2 5.2.1 UsingtheStack...89 5.2.2 UsingtheAlternate64KRAMBank...89 5.2.2.1 ProtectingAuxiliaryBankHiResGraphicsPages...89 5.2.2.2 Disconnecting/RAM...90 5.2.2.3 HowtoTreatRAMDisksWithMoreThan64K...91 5.2.2.4 Reinstalling/RAM...92 5.2.3 TheSystemGlobalPage...94 5.2.4 RulesforUsingtheSystemGlobalPage...94 GeneralTechniques...98 5.3 5.3.1 DeterminingMachineConfiguration...98 5.3.1.1 MachineType...98 5.3.1.2 MemorySize...98 5.3.1.3 80ColumnTextCard...99 5.3.2 UsingtheDate...99 5.3.3 SystemProgramDefaults...100 5.3.4 FindingaVolume...100 5.3.5 UsingtheRESETVector...101 ProDOSSystemProgramConventions...101 5.4

Pageix

Chapter6 AddingRoutinestoProDOS...103 Clock/CalendarRoutines...104 6.1 6.1.1 OtherClock/Calendars...106 InterruptHandlingRoutines...106 6.2 6.2.1 InterruptsDuringMLICalls...108 6.2.2 SampleInterruptRoutine...109 DiskDriverRoutines...112 6.3 6.3.1 ROMCodeConventions...112 6.3.2 CallParameters...114 AppendixA TheProDOSBASICSystemProgram...117 MemoryMap...118 A.1 HIMEM...120 A.2 A.2.1 BufferManagement...121 TheBASICGlobalPage...123 A.3 A.3.1 BASIC.SYSTEMCommandsFromAssemblyLanguage...131 A.3.2 AddingCommandstotheBASICSystemProgram...134 A.3.2.1 BEEPExample...136 A.3.3.2 BEEPSLOTExample...138 A.3.3 CommandStringParsing...140 ZeroPage...142 A.4 TheExtended80ColumnTextCard...143 A.5

Pagex AppendixB FileOrganization...145 FormatofInformationonaVolume...146 B.1 FormatofDirectoryFiles...147 B.2 B.2.1 PointerFields...148 B.2.2 VolumeDirectoryHeaders...148 B.2.3 SubdirectoryHeaders...151 B.2.4 FileEntries...154 B.2.5 ReadingaDirectoryFile...157 FormatofStandardFiles...159 B.3 B.3.1 GrowingaTreeFile...159 B.3.2 SeedlingFiles...161 B.3.3 SaplingFiles...162 B.3.4 TreeFiles...163 B.3.5 UsingStandardFiles...163 B.3.6 SparseFiles...164 B.3.7 LocatingaByteinaFile...166 DiskOrganization...167 B.4

B.4.1 StandardFiles...169 B.4.2 HeaderandEntryFields...170 B.4.2.1 Thestorage_typeAttribute...171 B.4.2.2 Thecreationandlast_modFields...171 B.4.2.3 TheaccessAttribute...172 B.4.2.3 Thefile_typeAttribute...172 DOS3.3DiskOrganization...174 B.5

Pagexi AppendixC ProDOS,theAppleIII,andSOS...175 ProDOS,theAppleIII,andSOS...176 C.1 FileCompatibility...176 C.2 OperatingSystemCompatibility...177 C.3 C.3.1 ComparisonofInput/Output...177 C.3.2 ComparisonofFilingCalls...177 C.3.3 MemoryHandlingTechniques...178 C.3.4 ComparisonofInterrupts...178 AppendixD TheProDOSMachineLanguageExerciser...179 HowtoUseIt...180 D.1 ModifyBuffer...181 D.2 Index ...183 TellAppleCard QuickReferenceCard

Pagexii

Figures and Tables

Chapter1 Introduction...1 Figure11 ASimplifiedDiagramofProDOS...2 Figure12 ATypicalProDOSDirectoryStructure...4 Figure13 TheLevelsofProDOS...8 Chapter2 FileUse...9 Figure21 ATypicalProDOSDirectoryStructure...12 Figure22 AutomaticMovementofEOFandMARK...15 Figure23 DirectoryFileStructure...18 Figure24 BlockOrganizationofaDirectoryFile...19

Figure25 BlockOrganizationofaStandardFile...19

Chapter3 MemoryUse...21 Figure31 MemoryMap...24 Chapter5 WritingaProDOSSystemProgram...81 Figure51 MemoryMap...83 Figure52 MemoryRepresentationintheSystemBitMap...84 Figure53 PageNumbertoBitMapBitConversion...85 Chapter6 AddingRoutinestoProDOS...103 Figure61 ProDOSDateandTimeLocations...104

Pagexiii AppendixA TheProDOSBASICSystemProgram...117 FigureA1 MemoryMap...119 TableA1 HIMEMandProgramWorkspace...120 FigureA2 TheMovementofHIMEM...121 FigureA3 ZeroPageMemoryMap...142 AppendixB FileOrganization...145 FigureB1 BlocksonaVolume...147 FigureB2 DirectoryFileFormat...148 FigureB3 TheVolumeDirectoryHeader...149 FigureB4 TheSubdirectoryHeader...152 FigureB5 TheFileEntry...155 FigureB6 StructureofaSeedlingFile...162 FigureB7 StructureofaSaplingFile...162 FigureB8 StructureofaTreeFile...163 FigureB9 ASparseFile...165 FigureB10 DiskOrganization...168 FigureB11 StandardFiles...169 FigureB12 HeaderandEntryFields...170 FigureB13 DateandTimeFormat...171 FigureB14 TheaccessAttributeField...172 TableB1 TheProDOSFile_Types...173 FigureB15 TracksandSectorstoBlocks...174

Pagexiv

PrefaceTheProDOSTechnicalReferenceManualisthelastofthree manualsthatdescribeProDOS(TM),themostpowerfuldiskoperating systemavailablefortheAppleII.

TheProDOSUser'sManualtellshowtocopy,rename,andremove ProDOSfilesusingtheProDOSFilerprogram,andhowtomovefiles fromDOSdiskstoProDOSdisksusingtheDOSProDOSConversion program. BASICProgrammingWithProDOSdescribesProDOStoauserof theBASICsystemprogram.Itexplainshowtostoreinformationon ProDOSdisksandtoretrieveinformationfromProDOSdisksusing ApplesoftBASIC. Thismanual,theProDOSTechnicalReferenceManual,explains howtousethemachinelanguageroutinesuponwhichtheFiler program,theDOSProDOSConversionprogram,andtheBASIC systemprogramarebased.AppendixArevealsamoretechnicalside oftheBASICsystemprogram.

About ProDOSThesetofmachinelanguageroutinesdescribedinthismanualprovides aconsistentandinterruptibleinterfacetoanyofthediskdevices manufacturedbyAppleComputer,Inc.fortheAppleII.Theyare designedtobeusedinprogramswritteninthe6502machinelanguage. Pagexv Thismanual

describesthefilesthattheseroutinescreateandaccess tellshoweachoftheroutinesisused explainshowtocombinetheroutinesintoanapplicationprogram tellshowtowriteandinstallroutinestobeusedwhenaninterrupt isdetected tellshowtowritearoutinethatautomaticallyreadsthedatefroma clock/calendarcardwhenafileiscreatedormodified explainshowtoattachotherdevicestoProDOS.

SomeadvantagesofprogramswrittenusingtheseProDOS machinelanguageroutinesare:

Theystoreinformationondisksusingahierarchicaldirectory structure. TheyareabletoaccessalldiskdevicesmanufacturedbyApple Computer,Inc.fortheAppleII. TheycanreaddatafromaDiskIIdriveatarateofapproximately eightkilobytespersecond(comparedtoonekilobytepersecondfor DOS). Theyareinterruptible. TheyhavethesamediskanddirectoryformatasAppleIIISOS disks. CallstoProDOSareverysimilartocallstoSOS;programscanbe readilydevelopedforboththeAppleIIandtheAppleIII. AppendixCexplainsthesimilaritiesanddifferencesbetweenProDOS andSOS.

About This ManualAppleII InthismanualthenameAppleIIimpliestheAppleIIPlus,the AppleIIe,andtheAppleIIc,aswellastheAppleII,unlessit specificallystatesotherwise. Thismanualiswrittentoserveasalearningtoolandareferencetool. Itassumesthatyouhavehadsomeexperiencewiththe6502assembly language,andthatyouarefamiliarwiththeAppleII'sinternal structure. Pagexvi IfyouhavereadBASICProgrammingWithProDOSandyouwantto findoutmoreabouthowtheBASICsystemprogramworks,referfirst toAppendixA.Ifyoustillwantmoredetails,Chapters1through3tell whatProDOSisandhowitworks.Ifyouplantowrite machinelanguageprogramsthatuseProDOS,youwillalsoneedto readChapters4and5.Chapter6showstechniquesforaddingvarious devicestotheProDOSsystem. Thismanualdoesnotexplain6502assemblylanguage.Ifyouplanto readbeyondChapter3,youshouldbefamiliarwiththe6502assembly languageandwiththeProDOSEditor/Assembler.

What These MeanBytheWay:Textsetoffinthismannerpresentssidelightsor interestingpointsofinformation. Important! Textsetoffinthismannerandwithataginthemarginpresents importantinformation. Warning Warningslikethisindicatepotentialproblemsordisasters.

About the Apple IIcAlthoughtheAppleIIchasnoslotsforperipheralcards,itis configuredasifitwereanAppleIIewith

128KbytesofRAM serialI/Ocardsinslots1and2 an80columntextcardinslot3 amouse(orjoystick)cardinslot4 adiskcontroller(fortwodiskdrives)inslot6.

Pagexvii Pagexviii

Chapter 1 IntroductionPage1 ThischaptercontainsanoverviewofProDOSandofthematerial explainedintherestofthismanual.Itpresentsaconceptualpictureof theorganizationandcapabilitiesofProDOS.Italsotellsyouwherein themanualeachaspectofProDOSisexplained.

1.1 - What Is ProDOS?ProDOSisanoperatingsystemthatallowsyoutomanagemanyofthe resourcesavailabletoanAppleII.Itfunctionsprimarilyasadisk operatingsystem,butitalsohandlesinterruptsandprovidesasimple meansformemorymanagement.ProDOSmarksfileswiththecurrent dateandtime,takenfromaclock/calendarcardifyouhaveone. AllProDOSstartupdiskshavetwofilesincommon:PRODOSand XXX.SYSTEM(Chapter2explainsthepossiblevaluesforXXX).The filePRODOScontainstheProDOSoperatingsystem;itperformsmostof thecommunicationbetweenasystemprogramandthecomputer's hardware.ThefileXXX.SYSTEMcontainsasystemprogram,the programthatusuallycommunicatesbetweentheuserandtheoperating system.Figure11showsasimplifiedblockdiagramoftheProDOS system.-----( User ) -----^ | v +------------------+ | System Program | +------------------+ ^ | v +------------------+ | Operating System | +------------------+ ^ | v +------------------+ | Hardware | +------------------+

From File xxx.SYSTEM

From File PRODOS

Disk Drives, Memory, and Slots

Page2 AProDOSsystemprogramsuchastheBASICsystemprogram(file BASIC.SYSTEMontheProDOSBASICProgrammingExamples disk),theProDOSFiler(fileFILERontheProDOSUser'sDisk),or theDOSProDOSConversionprogram(fileCONVERTontheProDOS User'sDisk)isanassemblylanguageprogramthatacceptscommands fromauser,makessuretheyarevalid,andthentakestheappropriate action.OnecourseofactionistomakeacalltotheMachineLanguage Interface(MLI),theportionoftheoperatingsystemthatreceives, validates,andissuesoperatingsystemcommands.

CallstotheMLIgiveyoucontrolovervariousaspectsofthehardware. MLIcallscanbedividedintohousekeepingcalls,filingcalls,memory calls,andinterrupthandlingcalls.ThewaythattheMLI communicateswithdiskdrives,memory,andinterruptdrivendevices isdescribedinthefollowingsections. CallstotheMLI:seeChapter4. AboutSystemPrograms:Ifyouhavedealtwithsystemprograms before,youmaybeabitconfusedaboutthetermasusedinthis manual.Truesystemprogramsareneitherapplicationprograms(such asawordprocessor)noroperatingsystems:theyprovideaneasy meansofmakingoperatingsystemcallsfromapplicationprograms. Asusedinthismanual,systemprogramreferstoaprogramthatis writteninassemblylanguage,makescallstotheMachineLanguage Interface,andadherestoasetofconventions,makingitrelativelyeasy toswitchfromonesystemprogramtoanother.Systemprogramscan beidentifiedbytheirfiletype. Inshort,itisthestructureofaprogram,notitsfunction,thatmakesa programaProDOSsystemprogram. TherulesfororganizingsystemprogramsaregiveninChapter5.

1.1.1 - Use of Disk DrivesAlthoughProDOSisabletocommunicatewithseveraldifferenttypes ofdiskdrives,thetypeofdiskdriveandtheslotlocationofthedrive neednotbeknownbythesystemprogram:theMLItakescareofsuch details.Insteaddisksor,moreaccurately,volumesofinformationare identifiedbytheirvolumenames. Theinformationonavolumeisdividedintofiles.Afileisanordered collectionofbytes,havinganame,atype,andseveralotherproperties. Oneimportanttypeoffileisthedirectoryfile:adirectoryfile containsthenamesandlocationonthevolumeofotherfiles.Whena diskisformattedusingtheFormataVolumeoptionoftheProDOS Filerprogram,amaindirectoryfileforthevolumeisautomatically Page3 placedonthedisk.Itiscalledthedisk'svolumedirectoryfile,andit hasthesamenameasthevolumeitself.Althoughitisinitiallyempty,

avolumedirectoryfilehasamaximumcapacityof51files. Anyfileinthevolumedirectorymayitselfbeadirectoryfile(calleda subdirectory),andanyfilewithinasubdirectorycanalsobea subdirectory.Usingdirectoryfiles,youcanarrangeyourfilessothat theycanbemosteasilyaccessedandmanipulated.Thisisespecially usefulwhenyouareworkingwithlargecapacitydiskdrivessuchas theProFile.AsampledirectorystructureisshowninFigure12. DirectorystructuresaredescribedinChapter2. Figure12.ATypicalProDOSDirectoryStructure+---------------+ +-----------------+ +-->| VIDEOBALL | +---->| PROGRAMS/ | | +---------------+ | |-----------------| | | | VIDEOBALL |--+ +---------------+ | | DISKWARS |----->| DISKWARS | | | | +---------------+ | +-----------------+ +-----------------+ | | /PROFILE/ | | |-----------------| | +---------------+ | PROGRAMS/ |--+ +-----------------+ +-->| MOM | | LETTERS/ |------->| LETTERS/ | | +---------------+ | SYSTEMPROGRAMS/ |----+ |-----------------| | | JUNK/ |--+ | | MOM |--+ +---------------+ +-----------------+ | | | DAD |----->| DAD | | | | SPOT |--+ +---------------+ | | +-----------------+ | | | | +---------------+ | | +-->| SPOT | | | +---------------+ | | | | | | +---------------+ | | +-----------------+ +-->| BASIC.SYSTEM | | +-->| SYSTEMPROGRAMS/ | | +---------------+ | |-----------------| | | | BASIC.SYSTEM |--+ +---------------+ | | FILER |----->| FILER | | | CONVERT |--+ +---------------+ | +-----------------+ | | | +---------------+ | +-->| CONVERT | | +---------------+ | | +-----------------+ +---->| JUNK | +-----------------+

Thefilingcalls,describedinChapter4,provideallfunctionsnecessary fortheaccessandmanipulationoffiles. Page4

1.1.2 - Volume and File CharacteristicsProgramsthatmakefilingcallstotheProDOSMachineLanguage Interfacecantakeadvantageofthefollowingfeatures:

AccesstoallProDOSformatteddisks;maximumcapacity 32megabytesonavolume. Filescanbestoredinupto64levelsofreadabledirectoryand subdirectoryfiles. Avolumedirectoryholdsupto51entries. Subdirectoriescanholdasmanyfilesasneeded;theybecomelarger asfilesareaddedtothem. Thereareover60distinctfileidentificationcodes;someare predefined,otherscanbedefinedbythesystemprogram.For compatibility,existingfiletypesshouldbeused. Uptoeightfilescanbeopenforaccesssimultaneously. Afilecanholdupto16megabytesofdata. Diskscanbeaccessedbyblocknumberaswellasbyfile. Ifthedatainafileisnotsequential,thelogicalsizeofthefilecan bebiggerthantheamountofdiskspaceused.

Theuseoffilesisdescribedin Chapter2;theirformatisgivenin AppendixB.

1.1.3 - Use of MemoryProDOStreatsmemoryasasequenceof256bytepages.Itrepresents thestatusofeachpage,usedorunused,asasinglebitinaportionof memorycalledthesystembitmap. WhenProDOSinitializesitself,itmarksallthepagesinmemoryit needstoprotect.Oncerunning,itsetsthecorrespondingbitinthebit mapforeachnewpageituses;whenitreleasesthepage,itclearsthe bit. Ifyourprogramallowstheusertoreadinformationintospecificareas ofmemory,youcanusethebitmaptopreventProDOSfrom overwritingtheprogram. ThearrangementofProDOSinmemory isdescribedinChapter3.

Page5

1.1.4 - Use of Interrupt Driven DevicesCertaindevicesgenerateinterrupts,signalsthattellthecontrolling computer(inthiscaseanAppleII),thatthedeviceneedsattention. ProDOSisabletohandleuptofourinterruptingdevicesatatime.To addaninterruptdrivendevicetoyoursystem: 1. 2. 3. 4. Placeaninterrupthandlingroutineintomemory. Marktheblockofmemoryasused. UsetheMLIcallthataddsinterruptroutinestothesystem. Enablethedevice.

Thiscausestheroutinetobecalledeachtimeaninterruptoccurs.If youinstallmorethanoneroutine,theroutineswillbecalledinthe orderinwhichtheywereinstalled. Toremoveaninterrupthandlingroutine: 1. Disablethedevice. 2. Unmarkitsblockinmemory 3. UsetheMLIcallthatremovesinterruptroutinesfromthesystem. Warning: Failuretofollowtheseproceduresinsequencemaycausesystem error. Theuseofinterruptdrivendevicesis describedinChapter6.

1.1.5 - Use of Other DevicesOtherthandisks,ProDOScommunicatesonlywithclock/calendar cards.Ifyoursystemhasaclock/calendarcardthatfollowsProDOS protocols(seeChapter6),ProDOSautomaticallysetsuparoutineso thatitcanreadfromtheclockbeforemarkingfileswiththetime.If youhavesomeothertypeofclock,youmustwriteyourownroutine, placeitinmemory,andtellProDOSwheretheroutineislocated. Page6

1.2 - SummaryFigure13illustratestheentiremechanismusedbyProDOSandshows theinteractionbetweenthelevelsofProDOS.AcompleteProDOS systemconsistsoftheMachineLanguageInterface,asystemprogram, andsomeexternalroutines.Ifyouwishyoursystemtooperatewith interruptdrivendevices,aclock/calendarcard,orotherexternal devices,youmustsupplyroutinesthatcommunicatewiththese devices. Thesystemprogramtakescommandsfromtheuserandissuesthemto theCommandDispatcherportionoftheMachineLanguageInterfaceor toindependentlycontrolleddevices.TheCommandDispatchervalidates eachcommandbeforepassingittotheBlockFileManager(whichalso managesmemory)ortotheInterruptReceiver/Dispatcher.TheBlock FileManagercallsadiskdriverroutineandtheclock/calendarroutine ifnecessary;theInterruptReceiver/Dispatchercallstheinterrupt handlingroutines. Page7 Figure13.TheLevelsofProDOSUSER IMA.USER -----( User )

-----^ - - - - - - - - - - - - - - - - - - - - - - - | - - - - - - - - - - - - - - - - - - - - - - - v +----------------+ USER INTERFACE | System Program | xxx.SYSTEM +----------------+ ^ ^ | \ v \ +------------+ \ - - - - - - - - - - - - - - - - - - - - | Command | - \ - - - - - - - - - - - - - - - - - - | Dispatcher | \ +------------+ \ ^ ^ +-------------------+ | | | +-----------------+ | | | | | v v | +------------+ +---------------------+ | PRODOS | Block File | | Interrupt | | OPERATING | Manager | | Receiver/Dispatcher | | SYSTEM +------------+ +---------------------+ |

^ | - - - - - v +-------------+ | Disk Driver | | Routines |

^ | v +----------------+ | Clock/Calendar | | Routine |

^ | +- - - - | - - - - - - - - - - - | - | | | | v +------------+ | Interrupt | | Routine(s) | v +-----------------+ | Other Device | | Driver Routines |

User Installed

+-------------+ +----------------+ | +------------+ +-----------------+ ^ ^ | ^ ^ - - - - - - - -|- - - - - - - - - | - - - - - -+- - - - | - - - - - - - - - | - - - - - - - - v v v v +---------+ +----------------+ +----------------+ +--------------+ HARDWARE | Disk II | | Clock/Calendar | | Interrupt | | Other Devices | | ProFile | | Card | | Driven Devices | | | +-----+ | +--------+ | +--------+ | +--------+ | | | | | | | | | +---+ +-------+ +-------+ +-----+

Thefollowingchaptersdescribetheimplementationofthismechanism. AfterreadingthroughChapter5,youwillbereadytostartwriting yourownsystemprograms.AfterreadingthroughChapter6,youwill beabletowriteyourownexternalroutines. Page8

Chapter 2 File UsePage9 Chapter1introducedyoutotheconceptsofvolumesandfiles.This chapterexplainshowfilesarenamed,howtheyarecreatedandused andalittleabouthowtheyareorganizedondisks.Whenyouhave finishedreadingthischapteryouwillbenearlyreadytostartusing theProDOSMachineLanguageInterfacefilingcalls. Thetechnicaldetailsoffileorganization aregiveninAppendixB.

2.1 - Using FilesAProDOSfilenameorvolumenameisupto15characterslong.It maycontaincapitalletters(AZ),digits(09),andperiods(.),andit mustbeginwithaletter.Lowercaselettersareautomaticallyconverted touppercase.Afilenamemustbeuniquewithinitsdirectory.Some examplesareLETTERS JUNK1 BASIC.SYSTEM

BytheWay:OntheAppleII,anASCIIcharacterisreadfromthe keyboardandprintedtothescreenwithitshighbitset.ProDOSclears thishighbit.

2.1.1 - PathnamesAProDOSpathnameisaseriesoffilenames,eachprecededbya slash(/).Thefirstfilenameinapathnameisthenameofavolume directory.Successivefilenamesindicatethepath,fromthevolume directorytothefile,thatProDOSmustfollowtofindaparticularfile. Themaximumlengthforapathnameis64characters,including slashes.Examplesare/PROFILE/GAMES/DISKWARS /PROFILE/JUNK1 /PROFILE/SYSTEMPROGRAMS/FILER

Allcallsthatrequireyoutonameafilewillaccepteitherapathname orapartialpathname.Apartialpathnameisaportionofapathname thatdoesn'tbeginwithaslashoravolumename.Themaximum lengthforapartialpathnameis64characters,includingslashes.These partialpathnamesareallderivedfromthesamplepathnamesabove. Page10 ThepartialpathnamesareDISKWARS JUNK1 SYSTEMPROGRAMS/FILER FILER

ProDOSautomaticallyaddstheprefixtothefrontofpartialpathnames toformfullpathnames.Theprefixisapathnamethatindicatesa directory;itisinternallystoredbyProDOS.Tolocateafilebyits

pathname,ProDOSmustlookthrougheachfileinthepath.Ifyou specifyapartialpathname,however,ProDOSjumpsstraighttothe prefixdirectoryandstartssearchingfromthere.Thusdiskaccessesare fasterwhenyousettheprefixandusepartialpathnames. Forthepartialpathnameslistedabovetoindicatevalidfiles,theprefix shouldbesetto/PROFILE/GAMES/,/PROFILE/, /PROFILE/,and/PROFILE/SYSTEMPROGRAMS/, respectively.Theslashesattheendoftheseprefixesareoptional; however,theyareconvenientremindersthatprefixesindicatedirectory files. Themaximumlengthforaprefixis64characters.Theminimum lengthforaprefixiszerocharacters,knownasanullprefix.Youset andreadtheprefixusingtheMLIcalls,SET_PREFIXand GET_PREFIX,respectively.The64characterlimitsfortheprefixand partialpathnamecombinetocreateamaximumpathnameof 128characters. Figure21illustratesatypicaldirectorystructure;itcontainsallthe filesmentionedabove. Page11 Figure21.ATypicalProDOSDirectoryStructure+---------------+ +-----------------+ +-->| VIDEOBALL | +---->| PROGRAMS/ | | +---------------+ | |-----------------| | | | VIDEOBALL -|--+ +---------------+ | | DISKWARS -|----->| DISKWARS | | | | +---------------+ | +-----------------+ +-----------------+ | | /PROFILE/ | | |-----------------| | +---------------+ | PROGRAMS/ |--+ +-----------------+ +-->| MOM | | LETTERS/ |------->| LETTERS/ | | +---------------+ | SYSTEMPROGRAMS/ |----+ |-----------------| | | JUNK/ |--+ | | MOM -|--+ +---------------+ +-----------------+ | | | DAD -|----->| DAD | | | | SPOT -|--+ +---------------+ | | +-----------------+ | | | | +---------------+ | | +-->| SPOT | | | +---------------+ | | | | | | +---------------+ | | +-----------------+ +-->| BASIC.SYSTEM | | +-->| SYSTEMPROGRAMS/ | | +---------------+

| |-----------------| | | | BASIC.SYSTEM -|--+ +---------------+ | | FILER -|----->| FILER | | | CONVERT -|--+ +---------------+ | +-----------------+ | | | +---------------+ | +-->| CONVERT | | +---------------+ | | +-----------------+ +---->| JUNK | +-----------------+

Page12

2.1.2 - Creating FilesAfileisplacedonadiskbytheCREATEcall.Whenyoucreateafile, youassignitthefollowingproperties:

Apathname.Thispathnameisauniquepathbywhichthefilecan beidentifiedandaccessed.Thispathnamemustplacethefilewithin anexistingdirectory. Anaccessbyte.Thevalueofthisbytedetermineswhetherornot thefilecanbewrittento,readfrom,destroyed,orrenamed. Afile_type.Thisbyteindicatestoothersystemprogramsthetype ofinformationtobestoredinthefile.Itdoesnotaffect,inany way,thecontentsofthefile. Astorage_type.Thisbytedeterminesthephysicalformatofthefile onthedisk.Thereareonlytwodifferentformats:oneisusedfor directoryfiles,theotherfornondirectoryfiles. Acreation_dateandacreation_time.

Whenyoucreateafile,thesepropertiesareplacedonthedisk.The file'snamecanbechangedusingtheRENAMEcall;otherproperties canbealteredusingtheSET_FILE_INFOcall.Thediskstorage formatofthesepropertiesisgiveninAppendixB. Onceafilehasbeencreated,itremainsonthediskuntilitis destroyed(usingtheDESTROYcall).

2.1.3 - Opening FilesBeforeyoucanreadinformationfromorwriteinformationtoafile youmustusetheOPENcalltoopenthefileforaccess.Whenyou openafileyouspecify:

Apathname.Thispathnamemustindicateapreviouslycreatedfile thatisonadiskmountedinadiskdrive. ThestartingaddressinmemoryofanI/Obuffer.Eachopenfile requiresitsown1024bytebufferforthetransferofinformationto andfromthefile.

TheOPENcallreturnsareferencenumber(ref_num).Allsubsequent referencestotheopenfilemustusethisreferencenumber.Thefile remainsopenuntilyouusetheCLOSEcall. Page13 Eachopenfile'sI/Obufferisusedbythesystemtheentiretimethe fileisopen.Thusitiswisetokeepasfewfilesopenaspossible.A maximumofeightfilescanbeopenatatime. Whenyouopenafile,someofthefile'scharacteristicsareplacedinto aregionofmemorycalledafilecontrolblock.Severalofthese characteristicsthelocationinmemoryofthefile'sbuffer,apointerto theendofthefile(theEOF),andapointertothecurrentpositionin thefile(thefile'sMARK)areaccessibletosystemprogramsviaMLI calls,andmaybechangedwhilethefileisopen. Itisimportanttobeawareofthedifferencesbetweenafileonthe diskandanopenfileinmemory.Althoughsomeofthefile's characteristicsandsomeofitsdatamaybeinmemoryatanygiven time,thefileitselfstillresidesonthedisk.ThisallowsProDOSto manipulatefilesthataremuchlargerthanthecomputer'smemory capacity.Asasystemprogramwritestothefileandchangesits characteristics,newdataandcharacteristicsarewrittentothedisk. Warning Iniscrucialthatyoucloseallfilesbeforeturningoffthe computerorpressing[CONTROL][RESET].Thisistheonlyway thanyoucanensurethatallwrittendatahasbeenplacedonthe disk.SeealsotheFLUSHcall.

2.1.4 - The EOF and MARKToaidthetasksofreadingfromandwritingtofiles,eachopenfile hasonepointerindicatingtheendofthefile,theEOF,andanother definingthecurrentpositioninthefile,theMARK.Botharemoved automaticallybyProDOS,butcanalsobeindependentlymovedbythe systemprogram.

TheEOFisthenumberofreadablebytesinthefile.Sincethefirst byteinafilehasnumber0,theEOF,whentreatedasapointer,points onepositionpastthelastcharacterinthefile. Whenafileisopened,theMARKissettoindicatethefirstbyteinthe file.Inisautomaticallymovedforwardonebyteforeachbytewritten toorreadfromthefile.TheMARK,then,alwaysindicatesthenext bytetobereadfromthefile,orthenextbytepositioninwhichto writenewdata.ItcannotexceedtheEOF. Page14 IfduringawriteoperationtheMARKmeetstheEOFboththeMARK andtheEOFaremovedforwardonepositionforeveryadditionalbyte writtentothefile.Thus,addingbytestotheendofthefile automaticallyadvancestheEOFtoaccommodatethenewinformation. Figure22illustratestherelationshipbetweentheMARKandtheEOF. Figure22.AutomaticMovementofEOFandMARKEOF | v +---------+ + | | | | | | | +---------+ + ^ | MARK Beginning Position EOF | v +---------+ + | | | | | | | +---------+ + ^ ^ | | Old MARK MARK After Reading Two Bytes EOF | v v +------------ + | | | | | | | | +------------ + ^ ^ | | Old MARK MARK After Writing Two Bytes Old EOF \

AsystemprogramcanplacetheEOFanywhere,fromthecurrent MARKpositiontothemaximumpossiblebyteposition.TheMARKcan beplacedanywherefromthefirstbyteinthefiletotheEOF.These twofunctionscanbeaccomplishedusingtheSET_EOFand SET_MARKcalls.ThecurrentvaluesoftheEOFandtheMARKcan bedeterminedusingtheGET_EOFandGET_MARKcalls.

2.1.5 Reading and Writing FilesREADandWRITEcallstotheMLItransferdatabetweenmemoryand afile.Forbothcalls,thesystemprogrammustspecifythreethings:

Thereferencenumberofthefile(assignedwhenthefilewas opened). Thelocationinmemoryofabuffer(data_buffer)thatcontains,or

istocontain,thetransferreddata.Notethatthiscannotbethe samebufferthatwasspecifiedwhenthefilewasopened. Thenumberofbytestobetransferred.

Whentherequesthasbeencarriedout,theMLIpassesbacktothe systemprogramthenumberofbytesthatitactuallytransferred. Page15 AreadorwriterequeststartsatthecurrentMARK,andcontinues untiltherequestednumberofbyteshasbeentransferred(or,ona read,untiltheendoffilehasbeenreached).Readrequestscanalso terminatewhenaspecifiedcharacterisread.Youturnonthisfeature andsetthecharacter(s)onwhichreadswillterminateusingthe NEWLINEcall.Itistypicallyusedforreadinglinesoftextthatare terminatedbycarriagereturns. BytheWay:NeitheraREADnoraWRITEcallnecessarilycausesa diskaccess.Itisonlywhenareadorwritecrossesa512byte(block) boundarythatadiskaccessoccurs.

2.1.6 - Closing and Flushing FilesWhenyoufinishreadingfromorwritingtoafile,youmustusethe CLOSEcalltoclosethefile.Whenyouusethiscall,youspecify

thereferencenumberofthefile(assignedwhenthefilewas opened).

CLOSEwritesanyunwrittendatatothefile,anditupdatesthefile's sizeinthedirectory,ifnecessary.Thenitfreesthe1024byte io_bufferforotherusesandreleasesthefile'sreferencenumber. Informationinthefile'sdirectory,suchasthefile'ssize,isnormally updatedonlywhenthefileisclosed.Ifyouweretopress [CONTROL][RESET](typicallyhaltingthecurrentprogram)whilea fileisopen,datawrittentothefilesinceitwasopenedcouldbelost andtheintegrityofthediskcouldbedamaged.Thiscanbeprevented byusingtheFLUSHcall.TouseFLUSHyouspecify

thereferencenumberofthefile(assignedwhenthefilewas opened).

Ifyoupress[CONTROL][RESET]whileanopenbutflushedfileisin

memory,thereisnolossofdataandnodamagetothedisk. BoththeCLOSEandFLUSHcalls,whenusedwithareferencenumber of0,normallycauseallopenfilestobeclosedorflushed.Specific groupsoffilescanbeclosedorflushedusingthesystemlevel. Page16

2.1.7 - File LevelsWhenafileisopened,itisassignedalevel,accordingtothevalueof aspecificbyteinmemory(thesystemlevel).Ifthesystemlevelis neverchanged,theCLOSEandFLUSHcalls,whenusedwitha referencenumberof0,causeallopenfilestobeclosedorflushed.But ifthelevelhasbeenchangedsincethefirstfilewasopened,onlythe fileshavingafilelevelgreaterthanorequaltothecurrentsystem levelareclosedorflushed. Thesystemlevelfeatureisused,forexample,bytheBASICsystem programtoimplementtheEXECcommand.AnEXECfileisopened withalevelof0,thenthelevelissetto7.ABASICCLOSEcommand (intendedtocloseallfilesopenedwithintheEXECprogram)closesall filesatorabovelevel7,buttheEXECfileitselfremainsopen.

2.2 - File OrganizationThisportionofthechapterdescribesingeneraltermstheorganization offilesonadisk.Itdoesnotattempttoteachyoueverythingabout fileorganization:itspurposeistofamiliarizeyouwiththetermsand conceptsrequiredbythefilingcalls. AppendixBelaboratesonthesubjectof fileorganization.

2.2.1 - Directory Files and Standard FilesEveryProDOSfileisanamed,orderedsequenceofbytesthatcanbe readfrom,andtowhichtherulesofMARKandEOFapply.However, therearetwotypesoffiles:directoryfilesandstandardfiles. Directoryfilesarespecialfilesthatdescribeandpointtootherfileson thedisk.Theymaybereadfrom,butnotwrittento(exceptby ProDOS).Allnondirectoryfilesarestandardfiles.Theymayberead fromandwrittento.

Adirectoryfilecontainsanumberofsimilarelements,calledentries. Thefirstentryinadirectoryfileistheheaderentry:itholdsthe nameandotherproperties(suchasthenumberoffilesstoredinthat directory)ofthedirectoryfile.Eachsubsequententryinthefile describesandpointstosomeotherfileonthedisk.Figure23 representsthestructureofadirectoryfile. Page17 Figure23.DirectoryFileStructureDirectory File Other Files

+--------------+ +--------------+ | | +---->| File | | Header Entry | | +--------------+ | | | |--------------| | +--------------+ | | | +-->| File | | Entry -|--+ | +--------------+ | | | |--------------| | | -|----+ | -|---> | More Entries-|--> | -|---> +--------------+ | -|------->| File | |--------------| +--------------+ | | | Entry -|---+ +--------------+ | | +--->| File | |--------------| +--------------+ | | | Entry -|---+ +--------------+ | | +--->| File | +--------------+ +--------------+

Thefilesdescribedandpointedtobytheentriesinadirectoryfilecan bestandardfilesorotherdirectoryfiles. Asystemprogramdoesnotneedtoknowthedetailsofdirectory structuretoaccessfileswithknownnames.Onlyoperationson unknownfiles(suchaslistingthefilesinadirectory)requirethe systemprogramtoexamineadirectory'sentries.Forsuchtasks,refer toAppendixB. Standardfileshavenosuchpredefinedinternalstructure:theformatof thedatadependsonthespecificfiletype.

2.2.2 - File StructureBecausedirectoryfilesaregenerallysmallerthanstandardfiles,and becausetheyaresequentiallyaccessed,ProDOSusesasimplerformof storagefordirectoryfiles.Bothtypesoffilesarestoredasasetof 512byteblocks,butthewayinwhichtheblocksarearrangedonthe diskdiffers. Adirectoryfileisalinkedlistofblocks:eachblockinadirectoryfile containsapointertothenextblockinthedirectoryfileaswellasa pointertothepreviousblockinthedirectory.Figure24illustratesthis structure. Page18 Figure24.BlockOrganizationofaDirectoryFile+------------+ +------------+ +------------+ | Key Block || | | | | | | | | | | | | | | | | | | | +------------+ +------------+ +------------+

Datafiles,ontheotherhand,areoftenquitelarge,andtheircontents mayberandomlyaccessed.Itwouldbeveryslowtoaccesssuchlarge filesiftheywereorganizedsequentially.InsteadProDOSstores standardfilesusingatreestructure.Thelargestpossiblestandardfile hasamasterindexblockthatpointsto128indexblocks.Eachindex blockpointsto256datablocksandeachdatablockcanhold512 bytesofdata.Theblockorganizationofthelargestpossiblestandard fileisshowninFigure25. Figure25.BlockOrganizationofaStandardFile+---------------------+ | Master Index | | Block | +---------------------+ | | | | | | | | | | | | v v v v | v v v v | +----------+ | +----------+ | | | v v v +-------------+ +-------------+ +-------------+ | Index | | Index | | Index | | Block 0 | | Block n | | Block 127 | +-------------+ +-------------+ +-------------+

| | | | v v | v +-------+ | Data | | Block | | 0 | +-------+

| | | v v | | v +-------+ | Data | | Block | | 255 | +-------+

| | | | v v | v +-------+ | Data | | Block | | 0 | +-------+

| | | v v | | v +-------+ | Data | | Block | | 255 | +-------+

| | | | v v | v +-------+ | Data | | Block | | 0 | +-------+

| | | v v | | v +-------+ | Data | | Block | | 255 | +-------+

Moststandardfilesdonothavethisexactorganization.ProDOSonly writesasubsetofthisstructuretothefile,dependingontheamount ofdatawrittentothefile.Thistechniqueproducesthreedistinctforms ofstandardfile:seedling,sapling,andtreefiles. AppendixBdescribesthethreeformsof standardfile. Page19

2.2.3 - Sparse FilesInmostinstancesaprogramwritesdatasequentiallyintoafile.By writingdata,movingtheEOFandMARK,andthenwritingmoredata, aprogramcanalsowritenonsequentialdatatoafile.Forexample,a programcanopenafile,writetencharactersofdata,andthenmove theEOFandMARK(therebymakingthefilebigger)to$3FE0before writingtenmorebytesofdata.Thefileproducedtakesuponlythree blocksonthedisk(atotalof1536bytes),yetover16,000bytescanbe readfromthefile.Suchfilesareknownassparsefiles. Important! Thefactthatmoredatacanbereadfromthefilethanactuallyresides onthediskcancauseaproblem.Supposethatyouweretryingtocopy asparsefilefromonedisktoanother.Ifyouweretoreaddatafrom onefileandwriteittoanother,thenewfilewouldbemuchlarger thantheoriginalbecausedatathatisnotactuallyonthediskcanbe readfromthefile.Thusifyoursystemprogramisgoingtotransfer sparsefiles,youmustusetheinformationinAppendixBtodetermine whichdatasegmentsshouldbecopied,andwhichshouldnot. TheProDOSFilerautomaticallypreservesthestructureofsparsefiles onacopy. Page20

Chapter 3 Memory UsePage21 ThischapterexplainsthewaytheMachineLanguageInterfaceuses memory.Ittellshowmuchmemorysystemprogramshaveavailableto them,howsystemprogramsshouldmanagethisfreememory,andit discussesthecontentsofimportantareasofmemorywhileProDOSis innuse.

3.1 - Loading SequenceWhenyoustartupyourAppleIIfromaProDOSstartupdiskone thatcontainsboththeMLI(ProDOS)andasystemprogram (XXX.SYSTEM)acomplexloadingsequenceisinitiated. Apreliminaryloadingprogramisstoredinthereadonlymemory(boot ROM)onadiskdrive'scontrollercard;themainpartoftheloader program,asitiscalled,residesinblocks0and1ofevery ProDOSformatteddisk. Whenyouturnonyourcomputer,oruseaPR#orIN#commandto referenceadiskdrivefromApplesoft,orotherwisetransfercontrolto theROMonthediskdrivecontrollercardwhenaProDOSstartupdisk isinthedrive,thisiswhathappens: 1. TheprogramintheROMreadstheloaderprogramfromblocks0 and1ofthedisk,placesitintomemorystartingatlocation$800, andthenexecutesit. 2. ThisloaderprogramlooksforthefilewiththenamePRODOSand type$FF(containingtheMLI)inthevolumedirectoryofthe startupdisk,loadsitintomemorystartingatlocation$2000,and executesit. 3. TheMLIascertainsthecomputer'smemorysizeandmovesitselfto itsfinallocation,asshowninFigure31.Nextitdetermineswhat devicesareinwhatslotsanditsetsupthesystemglobalpage, describedinthesection"TheSystemGlobalPage,"forthissystem configuration. 4. TheMLIthensearchesthevolumedirectoryofthebootdiskfor thefirstfilewiththenameXXX.SYSTEMandtype$FF,loadsit intomemorystartingat$2000,andexecutesit.

IfPRODOScannotbefound,theloaderreportstotheuserthatitis unabletoloadProDOS.IfnoXXX.SYSTEMprogramisfound,ProDOS displaysthemessageUNABLE TO FIND A SYSTEM FILE. Therulesforsystemprogramsare describedinChapter5. Page22 TheMLIisentirelymemoryresident.Onceitisinmemory,itneither moves,nordoesitrequireanyadditionaldiskaccesses(althoughthe systemprogrammight).Thememoryconfigurationthatresultsfrom thisloadingprocessisdescribedinthesection"MemoryMap."

3.2 - Volume Search OrderWhenaprogramoruserrequestsaccesstoavolumethatProDOShas notyetaccessed,itmustsearchthroughthevolumesthatare currentlyonlinefortherequestedvolume.Theorderinwhichit searchesthedevicesisdeterminedduringstep3above. Thefirstvolumecheckedis/RAM,ifpresent,thenthestartupvolume (generallyslot6,drive1).Thesearchthenchecksslotsindescending slotorder,startingwithslot7.Inanyslot,drive1issearchedbefore drive2. Forexample,iftherearetwoDiskIIdrivesinslot6,twoDiskII drivesinslot5,andaProFileinslot7,thesearchorderis: /RAM Slot6,drive1 Slot6,drive2 Slot7 Slot5,drive1 Slot5,drive2 Thestartupvolumeisthevolumeinthehighestnumberedslotthat canbeidentifiedbythesystemasastartupvolume.Thissequenceis keptinthedevicelistintheProDOSglobalpageandcanbealtered. Note:Ifthestartupvolumeisaharddisk,thesearchorderisfrom slot7toslot1.

3.3 - Memory MapProDOSrequiresatleast64kilobytesofmemory.Figure31isthe ProDOSmemorymap. Page23 Figure31.MemoryMapMain Memory Auxiliary Memory (IIc or 128K IIe only)

$FFFF+---------+$FFFF+---------+ $FFFF+---------+ |.Monitor.| |#########| |.........| $F800|---------| |#########| |.........| |.........| |#########| |.........| |.........| |#########| |.........| |.........| |#########| |.........| |.........| |#########| |.........| |.........| |#########| |.........| |.........| |#ProDOS##| |.........| |Applesoft| |#########|$DFFF+---------+$E000|---------|$DFFF+---------+ |.........| |#########| |.........| | | |.........| |.........| |#########| |.........| | | |.........| |.........| |#########|$D400|---------| | | |.........| |.........| |#########| |#########| | | |.........| |.........| |#########|$D100|---------| | |$D100|---------| |.........| |#########| | | | | | | $D000|---------| +---------+ +---------+$D000+---------+ +---------+ |..Other..| $C100+---------+ ^ $BFFF+---------+ $BFFF+---------+ | |#########| |.........| This ROM area| $BF00|---------| $BF00|---------| on IIc and IIe |\\\\\\\\\| | | only! |\\\\\\\\\| | | +---------+ |\\\\\\\\\| | | |#########| |\\\\\\\\\| | | +---------+ |\\\\\\\\\| | | Used by ProDOS |\BASIC.\\| | | |\SYSTEM\\| | | |\\\\\\\\\| | | +---------+ |\\\\\\\\\| | | |\\\\\\\\\| |\\\\\\\\\| | | +---------+ |\\\\\\\\\| | | Used by |\\\\\\\\\| | | BASIC.SYSTEM $9600|---------| | | | | | | | | | | +---------+ | | | | |.........| | | | | +---------+ | | | | Other used or | | | | reserved areas | | | | | | | | | | | | +---------+ | | | | | | | | | | +---------+

| | | | /\/\/\/\/\/ /\/\/\/\/\/ | | | | | | | | | | $800|---------| |.........| |.........| |.........| |.........| |.........| $300|---------| | | $300|---------| |.........| |.........| $100|---------| | | | | $4F|---------| |#Shared/#| |####safe#| $3A|---------| | | +---------+ $00

| | | | /\/\/\/\/\/ /\/\/\/\/\/ | | | | | | | | | | $800|---------| |.........| |.........| |.........| $400|---------| |#########| |#########| |#########| |#########| $200|---------| | | $100|---------| |#########| $80|---------| | | | | | | | | | | +---------+

Free Space

Page24 Asystemprogramaslargeas$8F00(36608)bytescanbeloadedintoa 64Ksystem.Thetotalamountofspaceavailabletoasystemprogram runningona64Ksystemis$B700(46848)bytes.

3.3.1 - Zero PageTheProDOSMachineLanguageInterfaceuseszeropagelocations $40$4E,butitrestoresthembeforeitcompletesacall.Thediskdriver routines,calledbytheMLI,uselocations$3Athrough$3F.These locationsarenotrestored.SeeChapter4fordetails.

3.3.2 - The System Global PageThe$BFpageofmemory,addresses$BF00through$BFFF,contains thesystem'sglobalvariables.Thissectionofmemoryisspecialbecause nomatterwhatsystemProDOSisbootedon,theglobalpageisalways inthesamelocation.Becauseofthisitservesasthecommunication linkbetweensystemprogramsandtheoperatingsystem.TheMLI

placesallinformationthatmightbeusefultoasystemprogramin theselocations.TheselocationsaredefinedanddescribedinChapter5.

3.3.3 - The System Bit MapProDOSusesasimpleformofmemorymanagementthatallowsitto protectitselfandtheuser'sdatafrombeingoverwrittenbyProDOS bufferallocation.Itrepresentsthelower48KoftheAppleII's randomaccessmemoryusingtwentyfourbytesofthesystemglobal page:onebitforeach256bytepageofRAMinthelower48Kofthe AppleII.Thesetwentyfourbytesarecalledthesystembitmap. WhenProDOSisstartedup,itprotectsthezeropage,thestack,and theglobalpage,bysettingthebitsthatcorrespondtotheusedpages. Ifatallpossible,asystemprogramshouldnotusepagesofmemory thatarealreadyused.Ifthisisnotpossible,thesystemprogrammust closeallfilesandclearthebitmap,leavingpages0,1,4through7, andBF(zeropage,stack,text,andProDOSglobalpage)protected.If anerroroccursontheclose,theprogramshouldasktheuserto restartthesystem.SeeChapter5fordetails. Page25 WhileasystemprogramisusingtheMLI,thereareonlythreecalls thataffectthesettingofthebitmap:OPEN,CLOSE,andSET_BUF. Whenthesystemprogramopensafile,itmustspecifythestarting addressofa1024bytefilebuffer.Aslongasthefileisopen,this bufferisapartofthesystem,andismarkedoffinthebitmap.When thefileisclosed,thebufferisreleased,anditsbitsarecleared. Ingeneral,asystemprogramrequirestheusedpagesofmemorytobe contiguous,ortouching.Thisleavesthemaximumpossibleunbroken memoryspaceforthereadingandmanipulationofdata.Supposea systemprogramopensseveralfilesandthenclosestheonethatwas openedfirst.Inmostcases,thiscausesavacant1Kareatoappear. TheGET_BUFandSET_BUFcallscanbeusedtofindthisvacant area,andtomoveanotherfile'sbufferintothisspace. RefertoChapter5foraspecificexample ofusingthesystembitmap. Page26

Chapter 4 Calls to the MLIPage27 ThischapterisabouttheProDOSMachineLanguageInterface(MLI), whichprovidesasimplewaytousediskfilesfrommachinelanguage programs.Thischapterdescribes

theorganizationoftheMLIonafunctionalbasis howtomakecallstotheMLIfrommachinelanguageprograms theMLIcallsthemselves theMLIerrorcodes.

4.1 - The Machine Language InterfaceTheProDOSMLIisacomplete,consistent,andinterruptibleinterface betweenthemachinelanguageprogrammerandfilesondisks.Itis entirelyindependentoftheProDOSBASICsystemprogram;thus,it servesasabaseuponwhichothersystemprogramscanbewritten.Its filenameisPRODOS.Itconsistsof:

theCommandDispatcher,whichacceptsanddispatchescallsfrom amachinelanguageprogram.Itvalidateseachcall'sparameters, updatesthesystemglobalpage,andthenjumpstotheappropriate routineoftheBlockFileManager. theBlockFileManager,whichcarriesoutallvalidcallstothe MLI.TheBlockFileManagerkeepstrackofallmounteddisks, managestheconditionofallopenedfiles,anddoessomesimple memorymangagement.Itperformsalldiskaccess(readsandwrites) viacallstodiskdriverroutines. DiskDriverRoutines,whichperformthereadingandwritingof data. theInterruptHandler,whichallowsuptofourinterrupthandling routinestobeattachedtoProDOS.TheInterruptHandlerkeepsfour vectorstointerruptroutines.Whenaninterruptoccurs,these routinesarecalled,insequence,untiloneofthemclaimsthe interrupt.

Page28

4.2 - Issuing a Call to the MLIAprogramsendsacalltotheMachineLanguageInterfaceby executingaJSR(jumptosubroutine)toaddress$BF00(referredto belowasMLI).Thecallnumberandatwobytepointer(lowbytefirst) tothecall'sparameterlistmustimmediatelyfollowthecall.Hereisan exampleofacalltotheMLI:SYSCALL JSR DB DW BNE MLI CMDNUM CMDLIST ERROR ;Call Command Dispatcher ;This determines which call is being made ;A two-byte pointer to the parameter list ;Error if nonzero

Uponcompletionofthecall,theMLIreturnstotheaddressofthe JSRplus3(intheaboveexample,theBNEstatement);thecall numberandparameterlistpointerareskipped.Ifthecallissuccessful, theCflagisclearedandtheAccumulatorissettozero.Ifthecallis unsuccessful,theCflagissetandtheAccumulatorissettotheerror code.Theregisterstatusuponcallcompletionissummarizedbelow. NotethatthevalueoftheNflagisdeterminedbytheAccumulator andthatthevalueoftheVflagisundefined.Successful call: Unsuccessful call: N 0 x Z 1 0 C 0 1 D 0 0 V x x Acc 0 error code PC JSR+3 JSR+3 X Y SP unchanged unchanged

Page29 HereisanexampleofasmallprogramthatissuescallstotheMLI.It triestocreateatextfilenamedNEWFILEonavolumenamed TESTMLI.Ifanerroroccurs,theAppleIIbeepsandprintstheerror codeonthescreen.Boththesourceandtheobjectaregivensoyou canenteritfromtheMonitorifyouwish(remembertousea formatteddisknamed/TESTMLI).-----------------------------------------------------------------------SOURCE FILE #01 =>TESTCMD ----- NEXT OBJECT FILE NAME IS TESTCMD.0 2000: 2000 1 ORG $2000 2000: 2000 1 ORG $2000 2000: 2 * 2000: FF3A 3 BELL EQU $FF3A ;Monitor BELL routine 2000: FD8E 4 CROUT EQU $FD8E ;Monitor CROUT routine 2000: FDDA 5 PRBYTE EQU $FDDA ;Monitor PRBYTE routine 2000: BF00 6 MLI EQU $BF00 ;ProDOS system call 2000: 00C0 7 CRECMD EQU $C0 ;CREATE command number 2000: 8 * 2000:20 06 20 9 MAIN JSR CREATE ;CREATE "/TESTMLI/NEWFILE" 2003:D0 08 200D 10 BNE ERROR ;If error, display it 2005:60 11 RTS ;Otherwise done

2006: 12 * 2006:20 00 BF 13 CREATE JSR MLI ;Perform call 2009:C0 14 DFB CRECMD ;CREATE command number 200A:17 20 15 DW CRELIST ;Pointer to parameter list 200C:60 16 RTS 200D: 17 * 200D:20 DA FD 18 ERROR JSR PRBYTE ;Print error code 2010:20 3A FF 19 JSR BELL ;Ring the bell 2013:20 8E FD 20 JSR CROUT ;Print a carriage return 2016:60 21 RTS 2017: 22 * 2017:07 23 CRELIST DFB 7 ;Seven parameters 2018:23 20 24 DW FILENAME ;Pointer to filename 201A:C3 25 DFB $C3 ;Normal file access permitted 201B:04 26 DFB $04 ;Make it a text file 201C:00 00 27 DFB $00,$00 ;AUX_TYPE, not used 201E:01 28 DFB $01 ;Standard file 201F:00 00 29 DFB $00,$00 ;Creation date (unused) 2021:00 00 30 DFB $00,$00 ;Creation time (unused) 2023: 31 * 2023:10 32 FILENAME DFB ENDNAME-NAME ;Length of name 2024:2F 54 45 53 33 NAME ASC "/TESTMLI/NEWFILE" ;followed by the name 2034: 2034 34 ENDNAME EQU * ------------------------------------------------------------------------

TheparametersusedinTESTCMDareexplainedinthefollowing sections.TheMLIerrorcodesaresummarizedinSection4.7. Page30

4.2.1 - Parameter ListsAsdefinedabove,eachMLIcallhasatwobytepointertoaparameter list.Aparameterlistcontainsinformationtobeusedbythecalland spaceforinformationtobereturnedbythecall.Therearethreetypes ofelementsusedinparameterlists:values,results,andpointers. AvalueisaoneormorebytequantitythatispassedtotheBlock FileManager(BFM).Valueshelpdeterminetheactiontakenbythe BFM. Aresultisaoneormorebytespaceintheparameterlistintowhich theBlockFileManagerwillplaceavalue.Fromresults,programscan getinformationaboutthestatusofavolume,file,orinterrupt,orabout thesuccessofthecalljustcompleted. Apointerisatwobytememoryaddressthatindicatesthelocationof data,code,oraspaceinwhichtheBlockFileManagercanplaceor receivedata.Allpointersarearrangedlowbytefirst,highbytesecond. Thefirstelementineveryparameterlististheparametercount,a

onebytevaluethatindicatesthenumberofparametersusedbythe call(notincludingtheparametercount).Thisbyteisusedtoverify thatthecallwasnotaccidental.

4.2.2 - The ProDOS Machine Language ExerciserTohelpyoulearntousetheProDOSMachineLanguageInterface, thereisausefullittleprogramcalledtheProDOSMachineLanguage Exerciser.ItallowsyoutoexecuteMLIcallsfromamenu;ithasa hexadecimalmemoryeditorforreviewingandalteringthecontentsof buffers;andithasacatalogcommand. InstructionsforusingtheMachine LanguageExerciserprogramarein AppendixD. WhenyouuseittomakeanMLIcall,yourequestthecallbyitscall number,thenyouspecifyitsparameterlist,justasifyouwerecoding thecallinaprogram.Whenyoupress[RETURN],thecallisexecuted. UsingtheExerciser,youcantryoutsequencesofMLIcallsbefore actuallycodingthem. Page31

4.3 - The MLI CallsTheMLIcallscanbedividedintothreegroups:housekeepingcalls, filingcalls,andsystemcalls.

4.3.1 - Housekeeping CallsThehousekeepingcallsperformoperationssuchascreating,deleting, andrenaming,whichcannotbeusedonopenfiles.Theyareusedto changeafile'sstatus,butnottheinformationthatisinthefile.They refertofilesbytheirpathnames,andeachrequiresatemporarybuffer, whichisusedduringexecutionofthecall.Thehousekeepingcallsare: CREATE Createseitherastandardfileora directoryfile.Anentryforthefileis placedintheproperdirectoryonthe disk,andoneblockofdiskspaceis

allocatedtothefile. DESTROY Removesastandardfileordirectory file.Theentryforthefileisremoved fromthedirectoryandallthefile's diskspaceisreleased.Ifadirectoryis tobedestroyed,itmustbeempty.A volumedirectorycannotbedestroyed exceptbyreformattingthevolume. RENAME Changesthenameofafile.Thenew namemustbeinthesamedirectoryas theoldname.Thiscallchangesthe nameintheentrythatdescribesthat file,andifitisadirectoryfile,also thenameinitsheaderentry. SET_FILE_INFO Setsthefile'stype,thewayitmaybe accessed,and/oritsmodificationdate andtime. GET_FILE_INFO Returnsthefile'stype,thewayitmay beaccessed,thewayitisstoredon thedisk,itssizeinblocks,andthe dateandtimeatwhichitwascreated andlastmodified. Page32 ON_LINE Returnstheslotnumber,drivenumber, andvolumenameofoneorall mountedvolumes.Thisinformationis placedinausersuppliedbuffer. SET_PREFIX Setsthepathnamethatisusedbythe operatingsystemasaprefix.The prefixmustindicateanexisting directoryonamountedvolume.

GET_PREFIX Returnsthevalueofthecurrent systemprefix.

4.3.2 - Filing CallsThefilingcallscausethetransferofdatatoorfromfiles.Thefirst filingcall,OPEN,mustbeusedbeforeanyoftheotherscanbeused. TheOPENcallspecifiesafilebyitspathname;theotherfilingcalls refertofilesbythereferencenumberreturnedbytheOPENcall.In addition,aninput/outputbuffer(io_buffer),isallocatedtotheopen file;subsequentdatatransfersgothroughthisbuffer.Thereference numberremainsassignedandthebufferremainsallocateduntilthefile isclosed.Thefilingcallsare: OPEN Preparesafiletobeaccessed.Thiscall causesafilecontrolblock(FCB)tobe allocatedtothefile,andareference numbertobereturned(Areference numberisreallyafilecontrolblock number).Inaddition,aninput/output bufferisallocatedfordatatransfersto andfromthefile. NEWLINE Setsconditionsforreadingfromthe file.Thiscallturnsonandturnsoff thecapabilityofreadrequeststo terminatewhenaparticularcharacter (suchasacarriagereturn)isread. READ Causesthetransferofarequested numberofcharactersfromafiletoa specifiedmemorybuffer,andupdates thecurrentposition(MARK)inthefile. Charactersarereadaccordingtothe rulessetbytheNEWLINEcall. Page33 WRITE Causesthetransferofarequested

numberofcharactersfromaspecified buffertoafile,andupdatesthe currentposition(MARK)inthefileand theendoffile(EOF),ifnecessary. CLOSE Transfersanyunwrittendatafroma file'sinput/outputbuffertothefile, releasesthefile'sio_bufferandfile controlblock,andupdatesthefile's directoryentry,ifnecessary.Thefile's referencenumberisreleasedforuseby subsequentlyopenedfiles. FLUSH Transfersanyunwrittendatafroma file'sinput/outputbuffertothefile, andupdatesthefile'sdirectoryentry, ifnecessary. SET_MARK Changesthecurrentpositioninthe file.Thecurrentpositionisthe absolutepositioninthefileofthenext charactertobereadorwritten. GET_MARK Returnsthecurrentpositioninthefile. Thecurrentpositionistheabsolute positioninthefileofthenext charactertobereadorwritten. SET_EOF Changesthelogicalsizeofthefile(the endoffile). GET_EOF Returnsthelogicalsizeofthefile. SET_BUF Assignsanewlocationforthe input/outputbufferofanopenfile. GET_BUF Returnsthecurrentlocationofthe

input/outputbufferofanopenfile. Page34

4.3.3 - System CallsSystemcallsarethosecallsthatareneitherhousekeepingnorfiling calls.Theyareusedforgettingthecurrentdateandtime,forinstalling andremovinginterruptroutines,andforreadingandwritingspecific blocksofadisk.Thesystemcallsare: GET_TIME Ifyoursystemhasaclock/calendar card,andifaroutinethatcanread fromtheclockisinstalled,thenit placesthecurrentdateandtimeinthe systemdateandtimelocations. ALLOC_INTERRUPT Placesapointertoan interrupthandlingroutineintothe systeminterruptvectortable. DEALLOC_INTERRUPT Removesapointertoaninterrupt handlingroutinefromthesystem interruptvectortable. READ_BLOCK Readsonespecificblock(512bytes)of informationfromadiskintoauser specifieddatabuffer.Thiscallisfile independent. WRITE_BLOCK Writesablockofinformationfroma userspecifieddatabuffertoaspecific blockofadisk.Thiscallisfile independent. Page35

4.4 - Housekeeping CallsEachofthefollowingsectionscontainsadescriptionofahousekeeping call,includingitsparametersandthepossibleerrorsthatmaybe returned.

4.4.1 - CREATE ($C0)7 6 5 4 3 2 1 0 +---+---+---+---+---+---+---+---+ | param_count = 7 | +---+---+---+---+---+---+---+---+ | pathname (low) | | (2-byte pointer) (high) | +---+---+---+---+---+---+---+---+ | access (1-byte value) | +---+---+---+---+---+---+---+---+ | file_type (1-byte value) | +---+---+---+---+---+---+---+---+ | aux_type (low) | | (2-byte value) (high) | +---+---+---+---+---+---+---+---+ | storage_type (1-byte value) | +---+---+---+---+---+---+---+---+ | create_date (byte 0) | | (2-byte value) (byte 1) | +---+---+---+---+---+---+---+---+ | create_time (byte 0) | | (2-byte value) (byte 1) | +---+---+---+---+---+---+---+---+

0 1 2 3 4 5 6 7 8 9 A B

Everydiskfileexceptthevolumedirectoryfilemustbecreatedusing thiscall.Therearetwoorganizationallydistincttypesoffilestorage: treestructure(storage_type=$1),usedforstandardfiles;andlinked list(storage_type=$D),usedfordirectoryfiles. Pathnamespecifiesthenameofthefiletobecreatedandthedirectory inwhichtoinsertanentryforthenewfile.Oneblock(512bytes)of diskspaceisallocated,andtheentry'skey_pointerfieldissetto indicatethatblock.Access,inmostcases,shouldbesetto$E3(full accesspermitted).File_typeandaux_typemaybeanything,butitis stronglyrecommendedthatconventionsbefollowed(seebelow). Page36 Parameters param_count (1bytevalue) Parametercount:7forthiscall.

pathname (2bytepointer) Pathnamepointer:Atwobyteaddress(lowbyte first)thatpointstoanASCIIstring.Thestring consistsofacountbyte,followedbythe pathname(upto64characters).Ifthepathname beginswithaslash(/),itistreatedasafull pathname.Ifnot,itistreatedasapartial pathnameandtheprefixisattachedtothefront tomakeafullpathname.Thepathnamestringis notchanged. access (1bytevalue) Accesspermitted:Thisbytedefineshowthefile willbeaccessible.Itsformatis:7 6 5 4 3 2 1 0 +--+--+--+--+--+--+--+--+ |D |RN|B |Reserved|W |R | +--+--+--+--+--+--+--+--+ D: RN: B: W: R: Destroy enable bit Rename enable bit Backup needed bit Write enable bit Read enable bit

Forallbits,1=enabled,0=disabled.Bits2 through4arereservedforfuturedefinitionand mustalwaysbedisabled.Usuallyaccessshould besetto$C3. Ifthefileisdestroy,rename,andwriteenabled, itisunlocked.Ifallthreearedisabled,itis locked.Anyothercombinationofaccessbitsis calledrestrictedaccess. Thebackupbit(B)isalwayssetbythiscall. file_type (1bytevalue) Filetype:Thisbytedescribesthecontentsofthe file.Thecurrentlydefinedfiletypesarelisted below. Page37File Type Preferred Use

$00 $01 $02 * $03 * $04 $05 * $06 $07 * $08 $09 * $0A * $0B * $0C * $0D,$0E * $0F $10 * $11 * $12 * $13 * $14 * $15 * $16-$18 * $19 $1A $1B $1C-$EE $EF $F0 $F1-$F8 $F9 $FA $FB $FC $FD $FE $FF

Typeless file (SOS and ProDOS) Bad block file Pascal code file Pascal text file ASCII text file (SOS and ProDOS) Pascal data file General binary file (SOS and ProDOS) Font file Graphics screen file Business BASIC program file Business BASIC data file Word Processor file SOS system file SOS reserved Directory file (SOS and ProDOS) RPS data file RPS index file AppleFile discard file AppleFile model file AppleFile report format file Screen library file SOS reserved AppleWorks Data Base file AppleWorks Word Processor file AppleWorks Spreadsheet file Reserved Pascal area ProDOS added command file ProDOS user defined files 1-8 ProDOS reserved Integer BASIC program file Integer BASIC variable file Applesoft program file Applesoft variables file Relocatable code file (EDASM) ProDOS system file

Note:Thefiletypesmarkedwitha*intheabovelistapplyto AppleIIISOSonly;theyarenotusedbyProDOS.Forthefile_types usedbyAppleIIISOSonly,refertotheSOSReferenceManual. Page38 aux_type (2bytevalue) Auxiliarytype:Thistwobytefieldisusedbythe systemprogram.TheBASICsystemprogramuses it(lowbytefirst)tostoretextfilerecordsizeor binaryfileloadaddress,dependingonthe file_type. storage_type (1bytevalue) Filekind:Thisbytedescribesthephysical

organizationofthefile.storage_type=$0Disa linkeddirectoryfile;storage_type=$01isa standardfile. create_date (2bytevalue) This2bytefieldmaycontainthedateonwhich thefilewascreated.Itsformatis:byte 1 byte 0

7 6 5 4 3 2 1 0 7 6 5 4 3 2 1 0 +-+-+-+-+-+-+-+-+ +-+-+-+-+-+-+-+-+ | Year | Month | Day | +-+-+-+-+-+-+-+-+ +-+-+-+-+-+-+-+-+

create_time (2bytevalue) This2bytefieldmaycontainthetimeatwhich thefilewascreated.Itsformatis:byte 1 byte 0

7 6 5 4 3 2 1 0 7 6 5 4 3 2 1 0 +-+-+-+-+-+-+-+-+ +-+-+-+-+-+-+-+-+ |0 0 0| Hour | |0 0| Minute | +-+-+-+-+-+-+-+-+ +-+-+-+-+-+-+-+-+

SeeChapter6forinformationaboutthe useofProDOSwithaclock/calendar card. Page39 PossibleErrors $27I/Oerror $2BDiskwriteprotected $40Invalidpathnamesyntax $44Pathnotfound $45Volumedirectorynotfound $46Filenotfound $47Duplicatefilename $48Overrunerror:notenoughdiskspace $49Directoryfull ProDOScanhavenomorethan51filesinavolumedirectory. $4BUnsupportedstorage_type $53Invalidparameter

$5ABitmapdiskaddressisimpossible

4.4.2 - DESTROY ($C1)7 6 5 4 3 2 1 0 +---+---+---+---+---+---+---+---+ 0 | param_count = 1 | +---+---+---+---+---+---+---+---+ 1 | pathname (low) | 2 | (2-byte pointer) (high) | +---+---+---+---+---+---+---+---+

Deletesthefilespecifiedbypathnamebyremovingitsentryfromthe directorythatownsit,andbyreturningitsblockstothevolumebit map.Volumedirectoryfilesandopenfilescannotbedestroyed. Subdirectoryfilesmustbeemptybeforetheycanbedestroyed. Page40 Parameters param_count (1bytevalue) Parametercount:1forthiscall. pathname (2bytepointer) Pathnamepointer:Atwobyteaddress(lowbyte first)thatpointstoanASCIIstring.Thestring consistsofacountbyte,followedbythe pathname(upto64characters).Ifthepathname beginswithaslash(/),itistreatedasafull pathname.Ifnot,itistreatedasapartial pathnameandtheprefixisattachedtothefront tomakeafullpathname. PossibleErrors $27I/Oerror $2BDiskwriteprotected $40Invalidpathnamesyntax $44Pathnotfound $45Volumedirectorynotfound $46Filenotfound $4AIncompatiblefileformat $4BUnsupportedstorage_type

$4EAccesserror:destroynotenabled $50Fileisopen:requestdenied $5ABitmapdiskaddressisimpossible Page41

4.4.3 - RENAME ($C2)7 6 5 4 3 2 1 0 +---+---+---+---+---+---+---+---+ | param_count = 2 | +---+---+---+---+---+---+---+---+ | pathname (low) | | (2-byte pointer) (high) | +---+---+---+---+---+---+---+---+ | new_pathname (low) | | (2-byte pointer) (high) | +---+---+---+---+---+---+---+---+

0 1 2 3 4

Changesthenameofthefilespecifiedbypathnametothatspecified bynew_pathname.Bothpathnameandnew_pathnamemustbe identicalexceptfortherightmostfilename(theymustindicatefilesin thesamedirectory).Forexample,thepath/EGG/ROLLcanbe renamed/EGG/PLANT,butnot/JELLY/ROLLor/EGG/DRUM/ROLL. Parameters param_count (1bytevalue) Parametercount:2forthiscall. pathname (2bytepointer) Pathnamepointer:Atwobyteaddress(lowbyte first)thatpointstoanASCIIstring.Thestring consistsofacountbyte,followedbythe pathname(upto64characters).Ifthepathname beginswithaslash(/),itistreatedasafull pathname.Ifnot,itistreatedasapartial pathnameandtheprefixisattachedtothefront tomakeafullpathname. new_pathname (2bytepointer) Newpathnamepointer:Thistwobytepointer (lowbytefirst)indicatesthelocationofthenew pathname.Ithasthesamesyntaxaspathname.

PossibleErrors $27I/Oerror $2BDiskwriteprotected $40Invalidpathnamesyntax $44Pathnotfound $45Volumedirectorynotfound $46Filenotfound Page42 $47Duplicatefilename $4AIncompatiblefileformat $4BUnsupportedstorage_type $4EAccesserror:renamenotenabled $50Fileisopen:requestdenied $57Duplicatevolume

4.4.4 - SET_FILE_INFO ($C3)7 6 5 4 3 2 1 0 +---+---+---+---+---+---+---+---+ | param_count = 7 | +---+---+---+---+---+---+---+---+ | pathname (low) | | (2-byte pointer) (high) | +---+---+---+---+---+---+---+---+ | access (1-byte value) | +---+---+---+---+---+---+---+---+ | file_type (1-byte value) | +---+---+---+---+---+---+---+---+ | aux_type (low) | | (2-byte value) (high) | +---+---+---+---+---+---+---+---+ | | | null_field (3 bytes) | | | +---+---+---+---+---+---+---+---+ | mod_date (byte 0) | | (2-byte value) (byte 1) | +---+---+---+---+---+---+---+---+ | mod_time (byte 0) | | (2-byte value) (byte 1) | +---+---+---+---+---+---+---+---+

0 1 2 3 4 5 6 7 8 9 A B C D

Modifiesinformationinthespecifiedfile'sentryfield.Thiscallcanbe performedwhenthefileiseitheropenorclosed.However,newaccess attributesarenotusedbyanopenfileuntilthenexttimethefileis opened(thatis,thiscalldoesn'tmodifyexistingfilecontrolblocks). YoushouldusetheGET_FILE_INFOcalltoreadafile'sattributes

intoaparameterlist,modifythemasneeded,andthenusethesame parameterlistfortheSET_FILE_INFOcall. Page43 Parameters param_count (1bytevalue) Parametercount:7forthiscall. pathname (2bytepointer) Pathnamepointer:Atwobyteaddress(lowbyte first)thatpointstoanASCIIstring.Thestring consistsofacountbyte,followedbythe pathname(upto64characters).Ifthepathname beginswithaslash(/),itistreatedasafull pathname.Ifnot,itistreatedasapartial pathnameandtheprefixisattachedtothefront tomakeafullpathname. access (1bytevalue) Accesspermitted:Thisbytedetermineshowthe filemaybeaccessed.Itsformatis:7 6 5 4 3 2 1 0 +--+--+--+--+--+--+--+--+ |D |RN|B |Reserved|W |R | +--+--+--+--+--+--+--+--+ D: RN: B: W: R: Destroy enable bit Rename enable bit Backup needed bit Write enable bit Read enable bit

Forallbits,1=enabled,0=disabled.Bits2 through4areusedinternallyandshouldbeset to0.Usuallyaccessshouldbesetto$C3. Ifthefileisdestroy,rename,andwriteenabled itisunlocked.Ifallthreearedisabled,itis locked.Anyothercombinationofaccessbitsis calledrestrictedaccess. Thebackupbit(B)issetbythiscall.

file_type (1bytevalue) Filetype:Thisbytedescribesthecontentsofa file.Thecurrentlydefinedfiletypesarelisted below. Page44File Type $00 $01 $02 * $03 * $04 $05 * $06 $07 * $08 $09 * $0A * $0B * $0C * $0D,$0E * $0F $10 * $11 * $12 * $13 * $14 * $15 * $16-$18 * $19 $1A $1B $1C-$EE $EF $F0 $F1-$F8 $F9 $FA $FB $FC $FD $FE $FF Preferred Use Typeless file (SOS and ProDOS) Bad block file Pascal code file Pascal text file ASCII text file (SOS and ProDOS) Pascal data file General binary file (SOS and ProDOS) Font file Graphics screen file Business BASIC program file Business BASIC data file Word Processor file SOS system file SOS reserved Directory file (SOS and ProDOS) RPS data file RPS index file AppleFile discard file AppleFile model file AppleFile report format file Screen library file SOS reserved AppleWorks Data Base file AppleWorks Word Processor file AppleWorks Spreadsheet file Reserved Pascal area ProDOS added command file ProDOS user defined files 1-8 ProDOS reserved Integer BASIC program file Integer BASIC variable file Applesoft program file Applesoft variables file Relocatable code file (EDASM) ProDOS system file

Note:Thefiletypesmarkedwitha*intheabovelistapplyto AppleIIISOSonly;theyarenotusedbyProDOS.Forthefile_types usedbyAppleIIISOSonly,refertotheSOSReferenceManual. Page45 aux_type (2bytevalue)

Auxiliarytype:Thistwobytefieldisusedbythe systemprogram.TheBASICsystemprogramuses it(lowbytefirst)tostorerecordsizeorload address,dependingonthefile_type. null_field (3bytes) Nullfield:Thesethreebytespreservesymmetry betweenthisandtheGET_FILE_INFOcall. mod_date (2bytevalue) This2bytefieldshouldcontainthecurrentdate. Ithasthisformat:byte 1 byte 0

7 6 5 4 3 2 1 0 7 6 5 4 3 2 1 0 +-+-+-+-+-+-+-+-+ +-+-+-+-+-+-+-+-+ | Year | Month | Day | +-+-+-+-+-+-+-+-+ +-+-+-+-+-+-+-+-+

mod_time (2bytevalue) This2bytefieldshouldcontainthecurrenttime. Ithasthisformat:byte 1 byte 0

7 6 5 4 3 2 1 0 7 6 5 4 3 2 1 0 +-+-+-+-+-+-+-+-+ +-+-+-+-+-+-+-+-+ |0 0 0| Hour | |0 0| Minute | +-+-+-+-+-+-+-+-+ +-+-+-+-+-+-+-+-+

SeeChapter6forinformationaboutthe useorProDOSwithaclock/calendar card. PossibleErrors $27I/Oerror $2BDiskwriteprotected $40Invalidpathnamesyntax $44Pathnotfound $45Volumedirectorynotfound $46Filenotfound $4AIncompatiblefileformat $4BUnsupportedstorage_type $4EAccesserror:filenotwriteenabled

$53Invalidvalueinparameterlist $5ABitmapdiskaddressisimpossible Page46

4.4.5 - GET_FILE_INFO ($C4)7 6 5 4 3 2 1 0 +---+---+---+---+---+---+---+---+ | param_count = $A | +---+---+---+---+---+---+---+---+ | pathname (low) | | (2-byte pointer) (high) | +---+---+---+---+---+---+---+---+ | access (1-byte result) | +---+---+---+---+---+---+---+---+ | file_type (1-byte result) | +---+---+---+---+---+---+---+---+ | aux_type (low) | * | (2-byte result) (high) | +---+---+---+---+---+---+---+---+ | storage_type (1-byte result) | +---+---+---+---+---+---+---+---+ | blocks used (low) | * | (2-byte result) (high) | +---+---+---+---+---+---+---+---+ | mod_date (byte 0) | | (2-byte result) (byte 1) | +---+---+---+---+---+---+---+---+ | mod_time (byte 0) | | (2-byte result) (byte 1) | +---+---+---+---+---+---+---+---+ | create_date (byte 0) | | (2-byte result) (byte 1) | +---+---+---+---+---+---+---+---+ | create_time (byte 0) | | (2-byte result) (byte 1) | +---+---+---+---+---+---+---+---+

0 1 2 3 4 5 6 7 8 9 A B C D E F 10 11

*Whenfileinformationaboutavolumedirectoryisrequested,the totalnumberofblocksonthevolumeisreturnedintheaux_typefield andthetotalblocksforallfilesisreturnedinblocks_used. GET_FILE_INFOreturnstheinformationthatisstoredinthe specifiedfile'sentryfield.Thiscallcanbeperformedwhetherthefile isopenorclosed.IftheSET_FILE_INFOcallisusedtochangethe accesswhilethefileisopen,thechangedoesnottakeeffectuntilthe filehasbeenclosedandreopened. Page47 Parameters

param_count (1bytevalue) Parametercount:$Aforthiscall. pathname (2bytepointer) Pathnamepointer:Atwobyteaddress(lowbyte first)thatpointstoanASCIIstring.Thestring consistsofacountbyte,followedbythe pathname(upto64characters).Ifthepathname beginswithaslash(/),itistreatedasafull pathname.Ifnot,itistreatedasapartial pathnameandtheprefixisattachedtothefront tomakeafullpathname. access (1byteresult) Accesspermitted:Thisbytedetermineshowthe filemaybeaccessed.Itsformatis:7 6 5 4 3 2 1 0 +--+--+--+--+--+--+--+--+ |D |RN|B |Reserved|W |R | +--+--+--+--+--+--+--+--+ D: RN: B: W: R: Destroy enable bit Rename enable bit Backup needed bit Write enable bit Read enable bit

Forallbits,1=enabled,0=disabled.Bits2 through4arenotused.Usuallyaccessshouldbe setto$C3. Ifthefileisdestroy,rename,andwriteenabled itisunlocked.Ifallthreearedisabled,itis locked.Anyothercombinationofaccessbitsis calledrestrictedaccess. file_type (1byteresult) Filetype:Thisbytedescribesthecontentsofa file.Thecurrentlydefinedfiletypesarelisted below. Page48

File Type $00 $01 $02 * $03 * $04 $05 * $06 $07 * $08 $09 * $0A * $0B * $0C * $0D,$0E * $0F $10 * $11 * $12 * $13 * $14 * $15 * $16-$18 * $19 $1A $1B $1C-$EE $EF $F0 $F1-$F8 $F9 $FA $FB $FC $FD $FE $FF

Preferred Use Typeless file (SOS and ProDOS) Bad block file Pascal code file Pascal text file ASCII text file (SOS and ProDOS) Pascal data file General binary file (SOS and ProDOS) Font file Graphics screen file Business BASIC program file Business BASIC data file Word Processor file SOS system file SOS reserved Directory file (SOS and ProDOS) RPS data file RPS index file AppleFile discard file AppleFile model file AppleFile report format file Screen library file SOS reserved AppleWorks Data Base file AppleWorks Word Processor file AppleWorks Spreadsheet file Reserved Pascal area ProDOS added command file ProDOS user defined files 1-8 ProDOS reserved Integer BASIC program file Integer BASIC variable file Applesoft program file Applesoft variables file Relocatable code file (EDASM) ProDOS system file

Note:Thefiletypesmarkedwitha*intheabovelistapplyto AppleIIISOSonly;theyarenotusedbyProDOS.Forthefile_types usedbyAppleIIISOSonly,refertotheSOSReferenceManual. Page49 aux_type (2byteresult) Auxiliarytype:Thistwobytefieldisusedbythe systemprogram.TheBASICsystemprogramuses it(lowbytefirst)tostorerecordsizeorload address,dependingonthefile_type.Ifthiscallis usedonavolumedirectoryfile,aux_typewill containthetotalnumberofblocksonthevolume. storage_type

(1byteresult) Filekind:Thisbytedescribesthephysical organizationofthefile.storage_type=$0Fisa volumedirectoryfile;storage_type=$0Disa directoryfile;storage_type=$01,$02,and$03 areseedling,sapling,andtreefiles,respectively (seeAppendixB).Allothervaluesarereserved forfutureuse. blocks_used (2byteresult) Blocksusedbythefile:Thesetwobytescontain thetotalnumberofblocksusedbythefile,as storedintheblocks_usedparameterofthefile's entry.Ifthiscallisusedonavolumedirectory fileblocks_usedcontainsthetotalnumberof blocksusedbyallthefilesonthevolume. mod_date (2byteresult) This2bytefieldreturnsthedateonwhichthe filewaslastmodified.Ithasthisformat:byte 1 byte 0

7 6 5 4 3 2 1 0 7 6 5 4 3 2 1 0 +-+-+-+-+-+-+-+-+ +-+-+-+-+-+-+-+-+ | Year | Month | Day | +-+-+-+-+-+-+-+-+ +-+-+-+-+-+-+-+-+

mod_time (2byteresult) This2bytefieldreturnsthetimeatwhichthe filewaslastmodified.Ithasthisformat:byte 1 byte 0

7 6 5 4 3 2 1 0 7 6 5 4 3 2 1 0 +-+-+-+-+-+-+-+-+ +-+-+-+-+-+-+-+-+ |0 0 0| Hour | |0 0| Minute | +-+-+-+-+-+-+-+-+ +-+-+-+-+-+-+-+-+

Page50 create_date (2byteresult) This2bytefieldreturnsthedateonwhichthe filewascreated.Ithasthisformat:

byte 1

byte 0

7 6 5 4 3 2 1 0 7 6 5 4 3 2 1 0 +-+-+-+-+-+-+-+-+ +-+-+-+-+-+-+-+-+ | Year | Month | Day | +-+-+-+-+-+-+-+-+ +-+-+-+-+-+-+-+-+

create_time (2byteresult) This2bytefieldreturnsthetimeatwhichthe filewascreated.Ithasthisformat:byte 1 byte 0

7 6 5 4 3 2 1 0 7 6 5 4 3 2 1 0 +-+-+-+-+-+-+-+-+ +-+-+-+-+-+-+-+-+ |0 0 0| Hour | |0 0| Minute | +-+-+-+-+-+-+-+-+ +-+-+-+-+-+-+-+-+

SeeChapter6forinformationaboutthe useofProDOSwithaclock/calendar card. PossibleErrors $27I/Oerror $40Invalidpathnamesyntax $44Pathnotfound $45Volumedirectorynotfound $46Filenotfound $4AIncompatiblefileformat $4BUnsupportedstorage_type $53Invalidvalueinparameterlist $5ABitmapaddressisimpossible

4.4.6 - ON_LINE ($C5)7 6 5 4 3 2 1 0 +---+---+---+---+---+---+---+---+ | param_count = 2 | +---+---+---+---+---+---+---+---+ | unit_num (1-byte value) | +---+---+---+---+---+---+---+---+ | data_buffer (low) | | (2-byte pointer) (high) | +---+---+---+---+---+---+---+---+

0 1 2 3

ThiscommandcanbeusedtodeterminethenamesofallProDOS(or SOS)volumesthatarecurrentlymounted(suchasdisksindisk drives),oritcanbeusedtodeterminethenameofadiskina specifiedslotanddrive.

Page51 Whenunit_numis0,thiscommandplacesalistofthevolumenames, slotnumbers,anddrivenumbersofallmounteddisksintothe 256bytebufferpointedtobydata_buffer.Whenaspecificunit_num isrequested,only16bytesneedbesetasideforthebuffer.Theformat ofthereturnedinformationisdescribedbelow. Thevolumenamesareplacedinthelistinvolumesearchorder,as describedinsection3.2. Parameters param_count (1bytevalue) Parametercount:Mustbe2forthiscall. unit_num (1bytevalue) Deviceslotanddrivenumber:Thisonebyte valuespecifiesthehardwareslotlocationofa diskdevice.Theformatis:7 6 5 4 3 2 1 0 +--+--+--+--+--+--+--+--+ |Dr| Slot | Unused | +--+--+--+--+--+--+--+--+

Fordrive1,Dr=0;fordrive2,Dr=1.Slot specifiesthedevice'sslotnumber(17).If unit_numis0,allmounteddisksarescanned. Herearepossiblevaluesforunit_num:Slot: Drive 1: Drive 2: 7 70 F0 6 60 E0 5 50 D0 4 40 C0 3 30 B0 2 20 A0 1 10 90

data_buffer (2bytepointer) Dataaddresspointer:Thistwobyteaddress(low bytefirst)pointstoabufferforreturneddata, whichisorganizedinto16byterecords.If unit_numis0,thebuffershouldbe256bytes long,otherwise16bytesisenough. Page52

Thefirstbyteofarecordidentifiesthedevice andthelengthofitsvolumename:7 6 5 4 3 2 1 0 +--+--+--+--+--+--+--+--+ |dr| slot | name_len | +--+--+--+--+--+--+--+--+

Bit7specifiesdrive1(Dr=0)ordrive2(Dr= 1).Bits64specifytheslotnumber(1through7). Bits30specifyavalidname_lengthifnonzero. Thenext15bytesoftherecordareforavolume name. Ifname_length=0,thenanerrorwasdetected inthespecifiedslotanddrive.Theerrorcodeis presentinthesecondbyteoftherecord.Iferror $57(duplicatevolume)isencountered,thethird bytecontainstheunitnumberoftheduplicate. Whenmultiplerecordsarereturned,thelastvalid recordisfollowedbyonethathasunit_numand name_lengthsetto0. Remember:ON_LINEreturnsvolumenamesthatarenotprecededby slashes.Remembertoputaslashinfrontofthenamebeforeyouuse itinapathname. PossibleErrors $27I/Oerror $28Devicenotconnected $2EDiskswitched:Filestillopenonotherdisk $45Volumedirectorynotfound $52NotaProDOSdisk $55VolumeControlBlockfull $56Badbufferaddress $57Duplicatevolume Whenanerrorpertainstoaspecificdrive,theerrorcodeisreturnedin thesecondbyteoftherecordcorrespondingtothatdrive,asdescribed above.Insuchcases,thecallcompleteswiththeaccumulatorsetto0, andthecarryflagclear.Onlyerrors$55and$56arenotdrivespecific. Page53

4.4.7 - SET_PREFIX ($C6)7 6 5 4 3 2 1 0 +---+---+---+---+---+---+---+---+ 0 | param_count = 1 | +---+---+---+---+---+---+---+---+ 1 | pathname (low) | 2 | (2-byte pointer) (high) | +---+---+---+---+---+---+---+---+

Setsthesystemprefixtotheindicateddirectory.Thepathnamemay beafullpathnameorapartialpathname.Thesystemprefixcanbe settonullbyindicatingapathnamewithacountofzero.Theprefix mustbenolongerthan64characters.WhenProDOSisstartedup,the systemprefixissettothenameofthevolumeinthestartupdrive. TheMLIverifiesthattherequestedprefixdirectoryisonanonline volumebeforeacceptingit. Parameters param_count (1bytevalue) Parametercount:1forthiscall. pathname (2bytepointer) Pathnamepointer:Atwobyteaddress(lowbyte first)thatpointstoanASCIIstring.Thestring consistsofacountbyte,followedbythe pathname(upto64characters).Ifthepathname beginswithaslash(/),itistreatedasafull pathname.Ifnot,itistreatedasapartial pathnameandthecurrentprefixisattachedto thefronttomakeafullpathname.Aslashatthe endofthepathnameisoptional. PossibleErrors $27I/Oerror $40Invalidpathnamesyntax $44Pathnotfound $45Volumedirectorynotfound $46Filenotfound $4AIncompatiblefileformat $4BUnsupportedstorage_type $5ABitmapdiskaddressisimpossible

Page54

4.4.8 - GET_PREFIX ($C7)7 6 5 4 3 2 1 0 +---+---+---+---+---+---+---+---+ 0 | param_count = 1 | +---+---+---+---+---+---+---+---+ 1 | data_buffer (low) | 2 | (2-byte pointer) (high) | +---+---+---+---+---+---+---+---+

Returnsthecurrentsystemprefix.Ifthesystemprefixissettonull (noprefix),thenacountof0isreturned.Otherwisethereturned prefixisprecededbyalengthbyteandbracketedbyslashes.Examples are$7/APPLE/and$D/APPLE/BYTES/.Eachcharacterintheprefix isreturnedwithitshighbitcleared. Thebufferpointedtobydata_bufferisassumedtobe64byteslong. Parameters param_count (1bytevalue) Parametercount:Mustbe1forthiscall. data_buffer (2bytepointer) Dataaddresspointer:Thistwobyteaddress(lowbytefirst)pointstothebufferintowhichthe prefixshouldbeplaced.Itshouldbeatleast 64byteslong. PossibleError $56Badbufferaddress Page55

4.5 - Filing CallsEachofthefollowingsectionscontainsadescriptionofafiling command,includingitsparametersandthepossibleerrorsthatmaybe returned.

4.5.1 - OPEN ($C8)7 6 5 4 3 2 1 0 +---+---+---+---+---+---+---+---+ | param_count = 3 | +---+---+---+---+---+---+---+---+ | pathname (low) | | (2-byte pointer) (high) | +---+---+---+---+---+---+---+---+ | io_buffer (low) | | (2-byte pointer) (high) | +---+---+---+---+---+---+---+---+ | ref_num (1-byte result) | +---+---+---+---+---+---+---+---+

0 1 2 3 4 5

OPENpreparesafiletobereadorwritten.Itcreatesafilecontrol blockthatkeepstrackofthecurrent(open)characteristicsofthefile specifiedbypathname,itsetsthecurrentpositioninthefiletozero, anditreturnsareferencenumberbywhichtheothercommandsin thissectionmustrefertothefile. TheI/Obufferisusedbythesystemfortheentiretimethefileis open.Itcontainsinformationaboutthefile'sstructureonthedisk,and itcontainsthecurrent512byteblockbeingreadorwritten.Itisused untilthefileisclosed,andthereforeshouldnotbemodifieddirectlyby theuser.Amaximumofeightfilescanbeopenatatime. Whenafileisopeneditisassignedalevel,from0to$F,depending onthecurrentvalueoftheLEVELlocation($BF94)inthesystem globalpage.WhentheCLOSEcommandisissuedwitharef_numof0, allfilesatorabovethecurrentlevelareclosed.Thus,aCLOSEwitha ref_numof0andalevelof0willcloseallopenfiles. RefertoSection2.1.7,"FileLevels,"for anexampleoftheuseoflevel. Warning Onceafilehasbeenopened,thatfile'sdiskmustnotberemoved fromitsdriveandreplacedbyanother.Thesystemdoesnot checktheidentityofavolumebeforewritingonit.Asystem programshouldcheckavolume'sidentitybeforewritingtoit. Page56 Parameters param_count (1bytevalue)

Parametercount:3forthiscall. pathname (2bytepointer) Pathnamepointer:Atwobyteaddress(lowbyte first)thatpointstoanASCIIstring.Thestring consistsofacountbyte,followedbythe pathname(upto64characters).Ifthepathname beginswithaslash(/),itistreatedasafull pathname.Ifnot,itistreatedasapartial pathnameandtheprefixisattachedtothefront tomakeafullpathname. io_buffer (2bytepointer) Bufferaddresspointer:Thistwobyteaddress (lowbytefirst)indicatesthestartingaddressofa 1024byteinput/outputbuffer.Thebuffermust startonapageboundary(amultipleof$100) thatisnotalreadyusedbythesystem. Ifastandardfileisbeingaccessed,thefirst 512bytesofio_buffercontainthecurrentblock ofdatabeingreadorwritten;thesecond 512bytescontainthecurrentindexblock,if thereisone.Ifadirectoryfileisbeingaccessed, thefirst512bytescontainthecurrentdirectory fileblock;therestareunused. ref_num (2byteresult) Referencenumber:Whenafileisopened,the filingsystemassignsthisonebytevalue.All subsequentcommandstotheopenfileusethis referencenumber. RefertoAppendixBformore informationondirectoryfileblocks, indexblocks,anddatablocks. PossibleErrors $27I/Oerror $40Invalidpathnamesyntax $42FileControlBlocktablefull $44Pathnotfound

$45Volumedirectorynotfound $46Filenotfound $4BUnsupportedstorage_type $50Fileisopen $53Invalidvalueinparameterlist $56Badbufferaddress $5ABitmapdiskaddressisimpossible Page57

4.5.2 - NEWLINE ($C9)7 6 5 4 3 2 1 0 +---+---+---+---+---+---+---+---+ | param_count = 3 | +---+---+---+---+---+---+---+---+ | ref_num (1-byte value) | +---+---+---+---+---+---+---+---+ | enable_mask (1-byte value) | +---+---+---+---+---+---+---+---+ | newline_char (1-byte value) | +---+---+---+---+---+---+---+---+

0 1 2 3

Thiscallallowsyoutoenableordisablenewlinereadmodeforany openfile.Whennewlineisdisabled,areadrequestterminateswhen therequestednumberofcharactershasbeenread,orwhentheendof fileisencountered.Whennewlineisenabled,areadrequestwillalso terminateifthenewlinecharacter(newline_char)isread. Eachcharacterreadisfirsttransferredtotheuser'sdatabuffer.Next itisANDedwiththeenable_maskandcomparedtothenewline_char. Ifthereisamatch,thereadisterminated.Forexample,if enable_maskis$7Fandnewline_charis$0D(ASCIICR),eithera $0Dor$8Dmatchesandterminatesinput.Thisprocessdoesnot changethecharacter. Parameters param_count (1bytevalue) Parametercount:3forthiscall. ref_num (1bytevalue) Referencenumber:Thisisthefilingreference numberthatwasassignedtothefilewhenitwas opened.

enable_mask (1bytevalue) Newlineenableandmask:Avalueof$00 disablesnewlinemode;anonzerovalueenables it.Whenthemodeisenabled,eachincomingbyte isANDedwiththisbytebeforeitiscomparedto newline_char(below).Amatchcausestheread requesttoterminate.Avalueof$FFmakesall bitssignificant,avalueof$7Fcausesonlybits0 through6tobetested,etc. newline_char (1bytevalue) Newlinecharacter:Whennewlineisenabled,a readrequestterminatesiftheinputcharacter, havingbeenANDedwiththeenable_mask equalsthisvalue. PossibleError $43Invalidreferencenumber Page58

4.5.3 - READ ($CA)7 6 5 4 3 2 1 0 +---+---+---+---+---+---+---+---+ | param_count = 4 | +---+---+---+---+---+---+---+---+ | ref_num (1-byte value) | +---+---+---+---+---+---+---+---+ | data_buffer (low) | | (2-byte pointer) (high) | +---+---+---+---+---+---+---+---+ | request_count (low) | | (2-byte value) (high) | +---+---+---+---+---+---+---+---+ | trans_count (low) | | (2-byte result) (high) | +---+---+---+---+---+---+---+---+

0 1 2 3 4 5 6 7

Triestotransfertherequestednumberofbytes(request_count), startingatthecurrentposition(MARK)ofthefilespecifiedby ref_numtothebufferpointedtobydata_buffer.Thenumberofbytes actuallytransferredisreturnedintrans_count. Ifnewlinereadmodeisenabledandanewlinecharacteris

encounteredbeforerequest_countbyteshavebeenread,thenthe trans_countparameterissettothenumberofbytestransferred, includingthenewlinebyte. Iftheendoffileisencounteredbeforerequest_countbyteshavebeen read,thentrans_countissettothenumberofbytestransferred.The endoffileerror($4C)isreturnedifandonlyifzerobyteswere transferred(trans_count=0). Page59 Parameters param_count Parametercount:4forthiscall. ref_num (1bytevalue) Referencenumber:Thisisthefilingreference numberthatwasassignedtothefilewhenitwas opened. data_buffer (2bytepointer) Dataaddresspointer:Thistwobyteaddress(low bytefirst)pointstothedestinationforthedatato bereadfromthefile. request_count (2bytevalue) Transferrequestcount:Thistwobytevalue(low bytefirst)specifiesthemaximumnumberof bytestobetransferredtothedatabufferpointed tobydata_buffer.Themaximumvalueislimited tothenumberofbytesbetweenthestartof data_bufferandthenearestusedpageof memory. trans_count (2byteresult) Transferred:Thistwobytevalue(lowbytefirst) indicatesthenumberofbytesactuallyread.It willbelessthanrequest_countonlyifEOFwas encountered,ifthenewlinecharacterwasread

whilenewlinemodewasenabled,orifsome othererroroccurredduringtherequest. PossibleErrors $27I/Oerror $43Invalidreferencenumber $4CEndoffilehasbeenencountered $4EAccesserror:filenotreadenabled $56Badbufferaddress $5ABitmapaddressisimpossible Page60

4.5.4 - WRITE ($CB)7 6 5 4 3 2 1 0 +---+---+---+---+---+---+---+---+ | param_count = 4 | +---+---+---+---+---+---+---+---+ | ref_num (1-byte value) | +---+---+---+---+---+---+---+---+ | data_buffer (low) | | (2-byte pointer) (high) | +---+---+---+---+---+---+---+---+ | request_count (low) | | (2-byte value) (high) | +---+---+---+---+---+---+---+---+ | trans_count (low) | | (2-byte result) (high) | +---+---+---+---+---+---+---+---+

0 1 2 3 4 5 6 7

Triestotransferaspecifiednumberofbytes(request_count)fromthe bufferpointedtobydata_buffertothefilespecifiedbyref_num startingatthecurrentposition(MARK)inthefile.Theactualnumber ofbytestransferredisreturnedintrans_count. Thefilepositionisupdatedtoposition+trans_count.Ifnecessary, additionaldataandindexblocksareallocatedtothefile,andEOFis extended. SeeAppendixBforanexplanationof dataandindexblocks. Page61 Parameters

param_count (1bytevalue) Parametercount:4forthiscall. ref_num (1bytevalue) Referencenumber:Thisisthefilingreference numberthatwasassignedwhenthefilewas opened. data_buffer (2bytepointer) Dataaddresspointer:Thistwobyteaddress(low bytefirst)pointstothebeginningofthedatato betransferredtothefile. request_count (2bytevalue) Transferrequestcount:Thistwobytevalue(low bytefirst)specifiesthemaximumnumberof bytestobetransferredfromthebufferpointedto bydata_buffertothefile. trans_count (2byteresult) Bytestransferred:Thistwobytevalue(lowbyte first),indicatesthenumberofbytesactually transferred.Ifnoerroroccurs,thisvalueshould alwaysbeequaltorequest_count. PossibleErrors $27I/Oerror $2BDiskwriteprotected $43Invalidreferencenumber $48Overrunerror:notenoughdiskspace $4EAccesserror:filenotwriteenabled $56Badbufferaddress $5ABitmapdiskaddressisimpossible Page62

4.5.5 - CLOSE ($CC)7 6 5 4 3 2 1 0 +---+---+---+---+---+---+---+---+ 0 | param_count = 1 | +---+---+---+---+---+---+---+---+ 1 | ref_num (1-byte value) | +---+---+---+---+---+---+---+---+

Thiscallisusedtoreleaseallresourcesusedbyanopenfile.Thefile controlblockisreleased.Ifnecessary,thefile'sbuffer(io_buffer)is emptiedtothefileandthedirectoryentryforthefileisupdated.Until thatref_numisassignedtoanotheropenfile,subsequentfilingcalls usingthatref_numwillfail. Ifref_numequalszero($0),allopenfilesatorabovethecurrent levelareclosed.Forexample,ifyouopenfilesatlevels0,1,and2, setthelevelto1,andthenuseCLOSEwithref_numsetto0,the filesatlevel1and2areclosed,buttheonesatlevel0arenot. Thelevelisavaluefrom0to$FthatisstoredintheLEVELlocation ($BFD8)ofthesystemglobalpage.Itisonlychangedbysystem programs,anditisusedbyOPENandCLOSE. Thiscallcausesthebackupbittobeset. Parameters param_count (1bytevalue) Parametercount:1forthiscall. ref_num (1bytevalue) Referencenumber:Thefilingreferencenumber thatwasassignedtothefilewhenitwasopened. CLOSEreleasesthisreferencenumber.If ref_num=0,allopenfilesatorabovethe currentlevelareclosed. PossibleErrors $27I/Oerror $2BDiskwriteprotected $43Invalidreferencenumber $5ABitmapdiskaddressisimpossible

Page63

4.5.6 - FLUSH ($CD)7 6 5 4 3 2 1 0 +---+---+---+---+---+---+---+---+ 0 | param_count = 1 | +---+---+---+---+---+---+---+---+ 1 | ref_num (1-byte value) | +---+---+---+---+---+---+---+---+

Thefile'swritebuffer(io_buffer)isemptiedtothefile,andthefile's directoryisupdated.Ifref_numequalszero($0),thenallopenfilesat orabovethecurrentlevelareflushed. Thebackupbitissetbythiscall. FLUSHisfurtherexplainedinChapter2, section"ClosingandFlushingFiles." Parameters param_count (1bytevalue) Parametercount:1forthiscall. ref_num (1bytevalue) Referencenumber:Thisisthefilingreference numberthatwasassignedtothefilewhenitwas opened.Ifref_num=0allopenfilesator abovethecurrentlevelareflushed. PossibleErrors $27I/Oerror $2BDiskwriteprotected $43Invalidreferencenumber $5ABitmapdiskaddressisimpossible Page64

4.5.7 - SET_MARK ($CE)7 6 5 4 3 2 1 0

+---+---+---+---+---+---+---+---+ 0 | param_count = 2 | +---+---+---+---+---+---+---+---+ 1 | ref_num (1-byte value) | +---+---+---+---+---+---+---+---+ 2 | (low) | 3 | position (3-byte value) | 4 | (high) | +---+---+---+---+---+---+---+---+

Changesthecurrentposition(MARK)inthefiletothatspecifiedby thepositionparameter.Positionmaynotexceedtheendoffile(EOF) value. SeetheexampleofSET_MARKin Chapter2,section"TheEOFandMARK." Parameters param_count (1bytevalue) Parametercount:2forthiscall. ref_num (1bytevalue) Referencenumber:Thefilingreferencenumber thatwasassignedtothefilewhenitwasopened. position (3bytevalue) Fileposition:Thisthreebytevalue(lowbytes first)specifiestotheFileManagertheabsolute positioninthefileatwhichthenextreador writeshouldbegin(theMARK).Thefileposition cannotexceedthefile'sEOF. PossibleErrors $27I/Oerror $43Invalidreferencenumber $4DPositionoutofrange $5ABitmapdiskaddressisimpossible Page65

4.5.8 - GET_MARK ($CF)7 6 5 4 3 2 1 0 +---+---+---+---+---+---+---+---+ | param_count = 2 | +---+---+---+---+---+---+---+---+ | ref_num (1-byte value) | +---+---+---+---+---+---+---+---+ | (low) | | position (3-byte result) | | (high) | +---+---+---+---+---+---+---+---+

0 1 2 3 4

Returnsthecurrentposition(MARK)inanopenfile. Parameters param_count (1bytevalue) Parametercount:2forthiscall. ref_num (1bytevalue) Referencenumber:Thefilingreferencenumber thatwasassignedtothefilewhenitwasopened. position (3byteresult) Fileposition:Thisthreebytevalue(lowbytes first)istheabsolutepositioninthefileatwhich thenextreadorwritewillbegin,unlessitis changedbyasubsequentSET_MARKcall. PossibleError $43Invalidreferencenumber Page66

4.5.9 - SET_EOF ($D0)7 6 5 4 3 2 1 0 +-