StreamsandFileDevicesEdited30Nov84,vanMelleAnInterlispStreamisanobjectofdatatypeSTREAMthatiscapableofperforming,attheleast,sequentialinputand/oroutputofbytes.Somestreamscandomuchmore.Streamsareusedforaccesstoopenfiles,forwritingtothedisplay,forchattingtoremotehosts,andwhateverotherusespeoplecomeupwith.Thisdocumentdescribeshowonegoesaboutdefininganewdevice,themeaningsoftherecordfieldsoftheSTREAMandFDEVdatatypes,andanythingelsethatseemedrelevantatthetime.TheimplementationofStreamsisstronglyobject-oriented.EverySTREAMhasapointertoadevice(thedatatypeFDEV),whichcontainsavectoroffunctionstobecalledwhencertainoperationsarerequiredofthestream.Therecanbemanystreamswiththesamedevice.Intheobject-orientedtermsofLOOPS,onecanthinkofthedeviceasaclass,whichprovidesasetofmethodsthatimplementclassoperations,andthestreamsasinstances.Devicesandstreamsalsohavelocalstate,whichmightbethoughtofasclassandinstancevariables.DeclarationsforSTREAMandFDEVcanbeobtainedbyloadingEXPORTS.ALL.OPENSTREAM,CLOSEF,FORCEOUTPUT,READP,EOFP,GETEOFPTR,GETFILEINFO,SETFILEINFO,DIRECTORY,COPYBYTES,DELFILE,RENAMEFILE,FULLNAMEaresomeoftheLispfunctionscalledbytheprogrammerthatultimatelyturnintooperationsatthedevicelevel.Thedescriptionsthatfollowsometimesalludetothesefunctions,andknowledgeofhowtheyoperatemayoccasionallygivethereaderadditionalcluesastohowthedeviceoperationswork.Typically,somepartoftheoperationishandledbythe``generic''filesystemcode,whichthencallsonthedevicetohandlethatpartoftheoperationthatisdevice-specific.Forexample,thefunctionOPENFILEtakesthenameofthefileitistoopenandfillsinhostanddirectorydefaults,anddecideswhichdevicehandlessuchafile.Itthencallsontheparticulardevicetoactuallyopenthefile.Afterthefileisopened,thegenericfilesystemcoderegistersthefileon(OPENP).Asanotherexample,operationsinvolvingopenstreamsfirstcoercenon-streams(e.g.filenames)toopenstreamsbeforecallingthedevice-specificoperation.DevicesAdeviceisanobjectoftypeFDEV(sonamedforhistoricalreasons:``FileDevice'').Thestandardwaytodefineanewdeviceistocreatesuchanobject,byperforming(createFDEV--),andthenpassthenewlycreatedFDEVtothefunction\DEFINEDEVICE.\DEFINEDEVICEisthewayadevice``announces''itselftothegenericfilesystem.(\DEFINEDEVICENAMEDEV)[Function]InstallsdeviceDEV,givingitthenameNAME.NAMEmustbeanuppercaselitatom.Thegenericfilesystemcodemakesuseofthenametolocatethedevicethatiswillingtodealwithfileswhosefullnamebegins{NAME}.Itispermissibletohavemorethanonenamemaptothesamedevice;thiseffectivelyprovidesdevicesynonyms.Devicesareencouraged,however,toalwayscreatefilenamesusingthecanonicaldevicename,independentofwhatnamewaspassedin.NAMEcanbeNIL,inwhichcasethegenericfilesystemcodeneverconsultsthedevicedirectly.However,itsEVENTFNisstillrunaroundLispexits,anditcanbeusedasthedeviceforastreamcreatedbynonstandardmethods. q?` p q?` g_paoq&**/I7|aorao7ao ]s [ c] Zar De%%ZatZa*ZarZa*-i.35 =>@Dr JJZa X u:$g&(,Y00z57:<@BKEHJJX VrH!W& ),26R9[=ACGAGJJV Tof|:f#X(*-143:a<->BFHJJT S0tS0rS0VS0tS0;S0rS0 W#&^(-2436d9_S0 O t&$m.?.22OtO7OrO8d:<@BCHJJO MaaMtMMrM +"-#)+.-04i8 ?VAFHJJM L1*Z F#W%)%-.5/2U;?A4A4LsLDLrLEHdJJL JF e(@JFuJFyJFrJF- $n%n'a((JFuJF-JFrJF. 07a:f A;CEJJJF Hi HiuHiHirHizw~"]%),046<=?BEJJHi F , FtFFrFV!!FtF%;FrF%')/1055FtF >FrF?PF Ct ZCrCyyCtCCrCCtC "CrC##CtC(1CrC)P)PCtC,CrC--CtC5ZCrC6y6yCtC ?CrC@@CtC JCrCJJC A?tA?rA?bbA?tA?A?rA?A?tA? A?rA?!!A?tA? )A?rA?**A?tA?1A?rA?24k79<?3E-HJJA? ?l  L!$ +s-D/4S8%8; CFJJ?l = ^#)+.169 AZDJFJJ= ; 6yzO &)`; 8g >\ "<')x+ 14U8BGJJ4 3  s}p\ #%r*j-02368;+<}ACHJJ3 16F/FF16t16$'16r16%%',2 9?CHJJ16 /c `  P#(X,w02; A/c *vj*r*p* '/ ,0'/t'/R'/r'/"&( .47 =>*AFIAJJ'/ %\ R!%' ..%\t%\/%\w%\4R%\r%\44%\t%\8;~%\r%\<<>ADFJJ%\ #t#tt#t#tr#tUkk#tt#t &V#tr#t''q'q#tt#t 2\#tr#t246A89> FIBJJ#t ! %H! 0t 0x00t00x0D0t00r0DL Ob0C/``CxCCrC !$7''CxC+^CrC,*,,CxC0CrC0357=BCcF)JJCy:b| "q$(V)-04'68&<>@CFJJyxr i ".#~ *,*/S258`<?@BF4JJ #,)*4/81s 9>@VDHJJ Q 1$E(. /1t483:>@l7x 7r77t7~7r7V"$'C,.e269?AmEJKK7dhhdtdIdrd "%),0236W8-;M<?&CNEpFJJd * $  q?`2Ifadeviceneverwantstobeinvokedbyname,andhasnointerestingEVENTFNorHOSTNAMEPmethods,thenthereisnoneedtoeverregisteritwith\DEFINEDEVICE.(\REMOVEDEVICEDEV)[Function]RemovesdeviceDEVfromthelistofknowndevices,aswellasanynamethatmapstothatdevice.(\GETDEVICEFROMNAMENAMENOERRORDONTCREATE)[Function]ReturnsthedeviceassociatedwithNAME.NAMEcanbealitatomorstring;itiscoercedtouppercase,andifitbeginswithanopenbrace,isassumedtobeafilename,fromwhichthehostnameisextracted.Ifnosuchdeviceisknown,attemptstofindonebypollingtheHOSTNAMEPmethodsofallknowndevices(seebelow);ifadeviceisstillnotfound,causesaFILENOTFOUNDerrorunlessNOERRORistrue.IfDONTCREATEistrue,itneverattemptstocreateadevice,justreturnsanexistingdeviceifthereisone,NILotherwise.ThefieldsofanFDEVaredividedupintoinformationalfieldsand``methods''.DEVICENAMEApointerfield,thenameofthedevice,standardlyalitatom.Useofthisfieldislargelyuptothedevice,butitisusuallyselectedtobethenamethatappearsinsidebracesinfilenamesopenedonthisdevice.Fordevicesthatdonotsupportthenotionofnamedfiles,DEVICENAMEcanbeanythingthattheimplementorcarestousefordebuggingassistance.RESETABLEAflag,trueif(SETFILEPTRstream0)canbeperformed.Currentlyunused.RANDOMACCESSPTrueifthestreamisrandomlyaccessable,i.e.,ifSETFILEPTRworksonthiskindofstream.NODIRECTORIESTrueiffilesopenedonthisdevicedonot(usually)haveadirectoryaspartoftheirname.TheprincipaluseforthisisbytheCONNcommand,whichwillnottrytoconnecttotheuser'shomedirectoryifgivenahostonly,e.g.,CONN{DSK}.BUFFEREDTrueifstreamsofthissortarebufferedinamannercompatiblewiththemicrocodedversionsofBINandBOUT.Morespecifically,BUFFEREDimpliesthatthedeviceimplementstheGETNEXTBUFFERmethod.Seedescriptionofbufferedstreams.PAGEMAPPEDTrueifthisstreamisimplementedbythepagemappedfunctions.Allpagemappedstreamsarealsobuffered,soifthisflagistrue,soshouldbeBUFFERED.Seedescriptionofpagemappedstreams.FDBINABLETrueifstreamsonthisdeviceobeytherulesformicrocodedBINwheneversuchstreamisopenforinputaccess.FDBOUTABLETrueifstreamsonthisdeviceobeytherulesformicrocodedBOUTwheneversuchstreamisopenforoutputaccess.Currentlyunused,asthespecneedsrevision.FDEXTENDABLESpecialkindofFDBOUTABLE.Currentlyunused,asthespecneedsrevision.DEVICEINFOApointertoarbitrarydevice-specificinformation.Thestandarduseforthisistoholdlocalstatespecifictooneofseveralsimilardevicesthatsharemethods.Forexample,$ fr hsp hsbrB ["7'_)F-H/2J4; ::btb@brbA,BBbtbJjbrbJJb`.G>"$\'2+-//`.t`. :`.r`.;;`. \t \x\\t\\r\DL Ob\YRffYxYYrY& ^"$&(*}/m035-7;1=A@BE_IxY VVtVVxVV8VVtVVVVxVV$VVtVV%%VVxVV -VVtVV.WVVrVVDL ObVVSiu #n&&SixSi*'SirSi+,++SixSi/RSirSi0246:<AVBDhIBJJSiQ ;&e #%x(,.35+78:k>kAEGJJQOE S"'#(-U24{7]9;@BBOtOJiOrOJJON5 #&l+,.<2469]=B(CkCkNtNGK@K@NL/L/rL/+}L/xL/"4L/rL/"#''k((L/xL/ 0L/rL/12j56:i?AgEIFUJJL/J\I""6#i&(**J\tJ\-[J\rJ\- 3J\ F !ooFtFFrF#I " *.x1 7F Cht ZChrCh/5 "&i'*5. 5.64;;s>?B)E1FwJJCh/A, !#%<&++0?1359<\AOE8IBJJA/?6!#&a*+E-2z5*79j>T@DFjJJ?/>kk>t> ">r>#N%'-]0!2w :=?BD;JJ>/<. <. 8t8r8/n#VV8t8 (8r8(-,-,8t8.8r8/213R :;:@E?8 5Ct 5Cr5C/."#* 03s445Ct5C =15Cr5C=ACF6I6JJ5C/3pu3p /t /r//#%(,.1R6:G;xALCEGJJ//.,h $'),.90X22.,t.,66.,r.,6=ADGHIBJJ.,/,Y#l',-1i2f508r;%;%,Yt,Y?XC,Yr,YC,Y (t(r(/| "a$')/m12+7' >$A0C JJ(/' {{' t' !' r' !$$' t' '' r' ()-r 44' t' ;' r'  tr/] W"1$(+.1H3X ::t=r=xC}FJJ/m!9% dt Zdrd/!"#>%*M-0535 =~=~dtd@drdAwGJJd/p"&@*u*057M9~<_@E  t  r / F F t ( r )[)/4638d;E>C t Z r /N$k-m 5-58W=@1BUDF.GJJ / c"\#&(B,1558<:BBE!JJ   q?`3theDolphindiskprovidesaseparateFDEVforeachpartitionofthemachine;theDEVICEINFOfieldofeachhaspointerstothepartition'sdirectoryandotherinformationspecifictofilesonthatpartitiononly.Thefollowingfieldsareallpointerfields,andcontainfunctionsforimplementingvariousdeviceoperations.Notalldevicesneedhaveallfieldsfilledin;therequiredonesarelistedfirstandsoindicated.Some``required''fieldshavedefaultsspecifiedintheFDEV(orSTREAM)recorddeclaration,sotheimplementorneednotexplicitlyfillthosefieldsifthedefaultisreasonable.Eachfieldispresentedwithitsarguments,inthestyleofafunctiondefinition;ofcourse,itisthecontentsofthefield,notthefieldname,thatisthefunction.Usingobject-orientedterminology,theoccupantsofthesefieldsarereferredtoas``methods''.Forexample,``theBINmethod''means``thefunctionthatoccupiestheBINfield''.Oneoftheargumentstoeachmethodisusuallyeitherthedeviceitself,orastreamopenonthedevice,sothatthedevice(andhenceitsDEVICEINFO)isusuallyaccessibletoallthesefunctions.Argumentsthatarefilenamesorpatternsorpiecesoffilenamescanbeeitherlitatomsorstrings,andalreadyhavetheirhostand/ordirectorypartsappropriatelyfilledinfromtheconnecteddirectorydefaults.Thedevicemayassumethatthehostfieldofthefilenameisindeedanamethatthedevicehassaiditimplements(seeHOSTNAMEP).``Full''filenamesreturnedbythesefunctions(orstoredintheFULLFILENAMEfieldofastream)shouldbelitatoms,andatleastinthecurrentimplementationshouldbealluppercase.Fieldsrequiredofeverydevice:(HOSTNAMEPHOSTNAMEDEVICE)Calledbythegenericfilesystemcodewhenpresentedwithahostnameforwhichthereisasyetnodevicedefined.Thefunctionshouldreturnnon-NILifit``recognizes''HOSTNAME.Therearetwowaysinwhichthismethodisinvoked:(1)ToobtainadeviceforHOSTNAME,forexample,sothatafilecanbeopenedonit.Inthiscase,DEVICEisanalreadydefineddevice(theonewhoseHOSTNAMEPmethodisbeingcalled),andthefunctionshouldreturneitheranewdevice,orT,meaningitiswillingtotakeresponsibilityforthishostnameaswellasanypreviousnameunderwhichthedevicewasregistered.Ineithercase,thecallerwillinstallthereturneddevice,orDEVICEifvaluewasT,asthedevicetowhichHOSTNAMEmaps.(2)Asapurepredicate.Inthiscase,DEVICEisNIL,andthefunctionneedonlyreturnTorNIL,indicatingwhetheritbelievesthatHOSTNAMEisthenameofahost.Inpractice,theHOSTNAMEPmethodneedonlytakecareofthefirstcase,sincethatalsotakescareofthesecondcase.Thesecondcaseisprovidedsothatthedeviceneednotbecreateduntilthereisanactualuseforit,shouldthedevicewishtoavoidunnecessarywork.Inpracticeitisrarethatanyonetestsahostnamewithoutsubsequentlyneedingtohavethedevicecreatedinfull.TherearebasicallythreekindsofdevicesinthesystemasdistinguishedbytheirHOSTNAMEPmethods.(1)Predefineddeviceswithexactlyonename,orstrictlyinternaldeviceswithnonotionofname.Forexample,theCOREdevicealwaysexists,andhasexactlyonename;theSPPdevice(anetworkbytestream)hasnoname(itsupportsnofilesdirectly).SuchdeviceshaveaHOSTNAMEPmethodofNILLtheonlynametheyevergobyistheonetheygaveto\DEFINEDEVICE,ifany.Thisisthedefault.J frIhspJjhs/brB"N')D..btb2brb258i>?BvHJJb/`.t `.r`. $&3),2S4g7, >D6GRJJ`./^[ #<$'z)R+1X4G^[ Z G_#%*i0L2s ;?C JKKZ Y  Z $U&).248Y;Q>)@ FtGJJY WV "$m&&WVtWV**WVrWV*,,WVtWV1WVrWV27H >@qB JJWV U = k|"=&(' /5/367x=@Bm IBJJU S ad  %d&(A*0&14Z7:o<@D<GHJJS Q C %!'c-/>26=8t=?'@ GHFJJQ P%uuP%tP%P%rP%R!')/1F1FP%tP%3P%rP%4#7P% L ] }!&E*,;0T35w6x:>?BFH"JJL J DxNNJtJ !JrJ"$( .0p2Q5 < <CFBHJJJ I|`"$&*/1G58q=#@KCqFJJJI GD 2 /#u%,177:9>[A>EHJJGD Ez |` n$&)-'/293r :=i=iEztEzDEzrEzF1FJJEz C 3M "&(P**CtC 4CrC479:?NCEeJJC A } ^( "'(* 0A >c CT>c ;&t 11;&x;&;&t;&;&x;&!;&t;&;&y;&;&89rQ#&*u03p4m77:<@DEMFHJJ896o;";&*-S6ot6o/6or6o091t2 :{:{6ox6oA%6or6oAB<FHDJJ6o4? h!&41!$#<#<1x1)1r1*,2`3679#BDFCFHOJJ1/AA/x//r/R$).I1=48K8K/t/?/r/@{EG&JJ/.K"&*./2688.t.9r.r.:*?@BFoGJJ.,H Au! #')Z,>-0~69=AD HCJJ,H*~ Wa %#D%}) +/n17;=*=**~x*~A*~r*~AC3FI:I:*~t*~J*~r*~JJ*~(a&!!(x('(r((+z(% ":"$X&**%x%.v%r%.0000%t%2%r%3w68V=@CGG%t%H%r%I+JJ%#te#r# B"_#(++++#x#1#r#2-3k59-:;>#!<!t!!X!r!!&),/2h3688< ?ZBDHJJ!4M#)%'',.]03.7B:p<>zCF)IJJ4jui!#a'*,Z0 7;`;=BCEWH"JJj) b$; ,C1I258<&@B?D 9#%*,Z.3T5 =y?BBtJjrJJ !$)S+0164;??CEI6JJ;W!6##;t;';r;'+0^4y7A9>qA,EuGG;t;Ji;r;JJ;hy!&O(*}./5"79 ?a?C GJJhtr?"V$$t'{r+I.q2?5^8q:q<|=@fC!F?IAJJ t  r { #x#&'*).  s q?`4(2)Devicesthatdon'tknowaheadoftimewhattheirnamewillbe,butforwhichtheremightbemanyincarnations.Thisisthemodelforremotefileservers.ThestandardwayofhandlingthiscaseistodefineadummydevicethathasonlyaHOSTNAMEPmethod,andnoname.WhentheHOSTNAMEPmethodgetscalledwithanamethatthedeviceknowsitcanservice,itcreatesadevicebythatname.Ifgivenanamethatisasynonymofanothername,itmightjustreturntheexistingdeviceofthecanonicalname(using\GETDEVICEFROMNAMEtofindtherightdevice).Ineithercase,theHOSTNAMEPmethodofthenewdeviceisusuallyNILLtheoriginaldeviceistheonlyonethatworriesaboutcreatingnewinstancesofthisclassofdevice.(3)Like(2),butallthedifferentnamesarehandledbyasingledevice,whichtakescareinternallyofthemultiplexingamong,say,differentremotehosts.HOSTNAMEPreturnsTinthiscase.Thisisusuallyclumsierthan(3),sodiscouraged.(EVENTFNDEVICEEVENT)CalledaroundLispexits,toallowthedevicetodoanynecessarycleaningup,clearingofcaches,disconnectswithremotehosts,etc.EVENTisoneofthefollowinglitatoms:BEFORELOGOUT,BEFORESYSOUT,BEFOREMAKESYS,BEFORESAVEVM,AFTERLOGOUT,AFTERSYSOUT,AFTERMAKESYS,AFTERSAVEVM,AFTERDOSYSOUT,AFTERDOMAKESYS,AFTERDOSAVEVM.TheAFTERxxxeventsareallrunwhenLispisbootedfromamemoryimagethatresultedfromaLOGOUT,SYSOUT,etc.TheAFTERDOxxxeventsrunwhencontinuingLispinthesameincarnationfollowingtheSYSOUT,etc.(thereisnosucheventforLOGOUT,ofcourse).The``after''eventsarecalledinthesameorderinwhichthedevicesweredefined;the``before''eventsinthereverseorder.Forexample,theBEFORELOGOUTeventfortheLeafremotefileserverdevicesperformsaFORCEOUTPUTonallitsopenfilesandthenbreakstheconnectionwiththefileserver.TheAFTERxxxeventsfortheLeafdevicescalls\REMOVEDEVICEonitselftoflushanyconnectionbetweenthenameandtheserver(sincenamesandaddressescanchangeoverexit).TheAFTERxxxeventsfortheDoradodiskdevicerebuildsitscacheofthedisk'sdirectory.ThereareafewdevicesinthesystemthatexistonlyfortheirEVENTFN.Inmostcases,asimplerwaytotellthesystemyouwantsomethingperformedaroundexitistoaddyoureventfunctiontothelistAROUNDEXITFNSinsteadofgoingtotheexpenseofdefiningadeviceforit.Thereisyetanotherlist,\SYSTEMCACHEVARS,forhandlingamorespecialized``aroundexit''operation:everytimeLispisbooted,eachofthevariablesinthelist\SYSTEMCACHEVARSissettoNIL.Thefollowingarerequiredofallnameddevices,thatis,devicesthatmapfromsomehostnametothedevice,uponwhichfilesmightbeopenedorotherwisemanipulated:(DIRECTORYNAMEPHOST/DIRDEVICE)TrueifHOST/DIRisavaliddirectorynameonDEVICE.Functionshouldideallyperformrecognitionaswell,andreturnthe``true''name.Forexample,given``{PHYLEX:}''asargument,itmightreturn{Phylex:PARC:Xerox}.HOST/DIRmightincludeasubdirectoryname.Thedeviceshouldattempttotellthetruthaboutwhetherthesubdirectoryexistsornot,thoughthismaynotbepossiblefordeviceswithfakesubdirectories.DefaultstoNILL,i.e.,devicesupportsnodirectories.UsedbythecommandCONNandthefunctionDIRECTORYNAMEP.(OPENFILENAMEACCESSRECOGPARAMETERSDEVICE). fr hsp hsbru $q(H),03693;R=?CFJJb`7 ""%'* .f058=*=@FI6JJ`7^m| &!%&+02589!9!^mt^m@^mr^mAF`HJJ^m\NN\t\&%\r\&+.:256-9<>BG'HeJJ\Z*1#O%''+,$-1258\9:@`AFJJZXkj$(a.47:AFJJXW3t"W3rW3#p% '*--i2g248j;==W3tW3EvW3rW3EJJW3U`9 %]%]U`tU`(U`rU`,|157<9<?kB<GJJU`S!F"%C(D)-SPOh d"(~,//467;@bDzHJJPN  %*-,27H;;w;wNtNCNrNCwHHNtNHNrNIAJJNM Ri"j'*-. 6M ItIxIItIIxIItIIFr !%3'+-Q/F17=1?DFJJJFE #&h''ExE*ErE+- /14::??EtE JErEJJECEt CErCECEtCE 'CErCE))CEtCE 3CErCE55CEtCE >CErCE@@CEtCE JCErCEJJCEArt ArrArArtAr % ArrAr&/&/ArtAr 1ArrAr2@2@ArtAr >ArrAr?(?(ArtAr JArrArJKKAr?PP?t??r? Z"0$(H+G,14h5z:>ArFIJJ?=t=r==t==r= ##=t=)=r=,1=4&8- ?TBDGrJJ=;  | |;t;%;r;&)'-D.04:8 :d:d;t;?n;r;@hB=GvHJJ;:&(^4 #&d)+/u16^9>A* FJJ:&8\BO8\5xu}5xt5x &*5xr5x&*-P/3R81:?DIJJ5x3t 3r3i u#&)-1m3 :>@CGHJJ31t1r1^ @#s(=+O+O1t1 6:1r168<-=AUC JJ1/:"e&*/V2K8;b@FCGUHJJ/.5t.5r.5,6Ev$O' +!0<1579@< B~.5+HwI "'.),/25B5B+Ht+H;#+Hr+H;AIDF JJ+H)uKZ M#* 05H79":=J@fCIBJJ)u''t' 'r' N$&*1+. 3%4:;%?MApCCoGUHJJ'%zz%t%%%r%&)R/004: ;?@DR JJ%$ 5"$&,?-/11$t$?n$r$?ABDsDs$t$F$r$GU$  >"')+d0 258:;tH9rIAJJ["r"rt7qr899x?r@EIJJ' o $&(-/W147;g@C JJ']K I#U%'- /R47@:JCaCIAJJ]tr `",$r +,w0J25%;;t?r?BEzJJ t S r  ztZZ zx z zt z zx z) zt z zx z zt z zx z ( zt z)) zx z- zt z. z A q?`y5UsedtoimplementtheOPENFILEandOPENSTREAMfunctions.OpensthefilenamedNAMEonthisdeviceforaccessACCESS,returningaSTREAM.ThestreamisusuallyonDEVICE(itsDEVICEfieldisDEVICE),butisnotrequiredtobe.TheargumentsACCESS,RECOG,PARAMETERSareaswiththeOPENFILEfunctioninthemanual.Thus,ifNAMEdoesnotincludeaversionnumber,recognitionisaccordingtoRECOG,whichshouldbeappropriatelydefaultedperACCESS(INPUTimpliesOLD,OUTPUTimpliesNEW,BOTHimpliesOLD/NEW).TheargumentNAMEcanalsobeaSTREAM,whichmustbeaclosedstream.OPENFILEshould``reopen''thestream.Thevaluereturnedinthiscasemaybeanewstream(withthesamenameastheold),ortheoldstream(NAME)itself.Itislikelythatthespecificationwillbechangedatsomepointtorequirethattheoldstreamitselfbereturned,suitablyreopened.TheargumentPARAMETERSisalistofpairs(OPTIONVALUE).ThemostinterestingOPTIONsareasfollows:TYPEFornewfiles,thetypeofthefile(TEXTorBINARY).Ifthisparameterisnotspecified,thevalueoftheglobalvariableDEFAULTFILETYPE(initiallyTEXT)shouldbeused.CREATIONDATEFornewfiles,thedateofitscreation.Thedeviceshouldusethisifatallpossibleinsteadoflettingthecreationdatedefaulttothecurrentdateandtime.LENGTHTheintendedlengthofthefile,inbytes.Thisneednotbeaccurateitisonlyahintthatmayallowsmarterallocation.Forexample,ifthedeviceknowsthatitdoesnothaveroomforafileofthespecifiedlength,itshouldimmediatelycauseaFILESYSTEMRESOURCESEXCEEDEDerrorfortheintendedfile.DON'T.CHANGE.DATEForoldfilesbeingopenedforaccessBOTH,don'tchangethecreationdateofthefile.ACCESS=BOTHwouldnormallyimplythatthecontentofthefileistochange,andthusitscreationdateshouldbeupdated.Useofthisparameterisaformof``cheating''tomakeitlookasthoughthefilehadnotchanged.Forexample,thecodethatrewritesfilemapsusesthisparameter,sincerewritingthefilemapdoesnotlogicallychangethefile'scontent.SEQUENTIALIfT,isahintthatthefilewill,orneed,onlybeaccessedsequentially,whichmayallowthedevicetoopenthefileinamoreefficientmode.Anyparametersthatthedevicedoesnotunderstandshouldbeignored,ratherthanbecauseforanerror.AlldevicesareencouragedtosupportatleastTYPEandCREATIONDATE.TheadditionaloptionsENDOSTREAMOPandBUFFERSarehandledbythegenericfilesystemcode;specifyingthemisequivalenttocallingSETFILEINFO(q.v.)immediatelyaftertheopen.FinepointaboutACCESS=OUTPUT:thisoperationalwaysproducesanew,emptyfile,independentofwhetheritsnameisexactlythenameofanexistingfile.Thatis,itreplacesanyoldfilebythesamename.Onopening,suchafilehasanendoffileofzero.Ofcourse,sinceRECOGdefaultstoNEWinthiscase,thenamecanonlyclashwithanoldfilenameifaversionwasexplicitlyspecified,orRECOGisOLDorOLD/NEW.Toopenanoldfileforoutputbutpreserveitscontents,i.e.,onlywriteoverpartofthefile,oneshouldopenforACCESS=BOTH(sincetopreservetheoldcontentsoneimplicitlyreadsthem).. z g,tIhspJjhsbr fbtb%dbrb%(o(obtb 0brb1A 7x7<>_@EEbxbHbrbHJJb`.3O;;`.x`.!`.r`."y(])h)h`.t`..r`.r`././2K67Y>Y`.x`.B`.r`.C.E`E``.t`.Jj`.r`.JJ`.^[^[x^[q^[r^[v &M'**-N33^[x^[8^[t^[99^[x^[=^[t^[>>^[x^[ F^[r^[GI@JJ^[\\t\\r\#"$.&+,-/1J1J\x\4\r\5<8_:?@EnJJ\Z = ZxZ$ZrZ%)./ 8X>\@@ZxZEDZrZEF6ZtZJiZrZJJZX''XtXXrX\\XtXfXrX"T"TXtX$XrX%%XtX(XrX)=--XtX3XrX4XU]yyUxUUrUl"$%%UtU*UrU+/245:>?F?FUtUEUrUFxJJUT" c: H#)9*-9/2458p<@"BZEI@JJT"RXf  RXxRX$RXrRX$(]((RXsRX)*-/1s 79;?4@WCEGJJRXPk4$"'&*PrP*PM=::MxM !MrM!r"#%'U**MxM/}MrM//MxM3MrM45U8;2 AAMxMF;MrMGI@JJMKBKHt?#@C2IJJHG)  &(8+-J/3z88G)tG)EG)rG)E} JJG)EVt!(EVrEV!&C(+EVBit BirBi"%L(+@-0d139.9 U#P>;t;r; &Q*,7.1L267[:n=@4B IJJ;: "$'*.j3^ 9:t=BDNFJJ:8K!$%(+9.a1457]8;8@E@FwJJ8K6 %)r**6t6/5?=D6r6E2HJJ64%'41t"'1r1"%(Q+|/47;d;d1t1>1r1?CHJJ1/#&'* ,-C-C/x/1/r/2C4"4"/t/7~/r/7<"AEHJJ/.$"$&M()+R0'257>2?mBhCHJJ,Z* "$**-s35U8u;@!E|HOJJ*( $(%.0m5r8;&@EDGJJ(&"&$t F$r$,,$t$ $r$ "#%(x*,/1x5 79? FJJ$"E $&K*_+/"1S35 6 9n>B?"Eai B#1&6( /y35:>ACfFHJJa+>d $&*,J/@/@t2r25}5}t ?r?{ t (r),b,bt2Cr25C:<?!CFuJJ! e %x&++++t 4hr48. ?BEHWCCx r!##t(r*6-*38[>@CH/JJ S $S%* ,C/1l368:; >*?@FHJJMQG &m)}*,/%035&7n9<@<>CFmFmMxMJiMrMJJMt&rP"%/) +.2t57:<<@BCbHCJJ S Cx!r"K##t&r&(*(*t. r./11846\8:= A\CIJJ nL#&'*[-5/48:l:l x > r ?AA t D r EIBJJ   E! '+X/0  q?`6Exceptionhandling:Ifthedesiredfileisnotfound,theOPENFILEmethodshouldreturnNILratherthancauseaFILENOTFOUNDerror.Thisissothatthegenericfilesystemcodecancausetheerrorusingtheoriginalfilename,nottheonepackedwithhostanddirectorypassedintotheOPENFILEmethod.Thedeviceshouldfeelfreetosignalanyothererrorsitselfonfailingtoopenthefile,e.g.,FILEWON'TOPENforabusyfile,PROTECTIONERROR,orFILESYSTEMRESOURCESEXCEEDED.Ideally,thiserrorshouldbesignaledinawaythatisresumable,i.e.,sothatausercould,inthebreak,takesomeactiontoremedytheconditionandthentypeOKtocontinue.InmostcasesitsufficesthatalltheinternalfunctionsbelowtheOPENFILEbenamedwithbackslashes,sothattheerrorcodewillchoosetoresumebyrevertingtotheOPENFILEandtryingagain.Thedevicedoesnotneedtoknowaboutthesetofopenfiles(i.e.,thevalueof(OPENP)),andingeneralshouldignoreit.Thatis,thedeviceshouldperformtheopenasiftherewerenootherfilesopenandhencenoconflict.ThegenericfilesystemcodelooksatthestreamreturnedfromtheOPENFILEmethodandthenworriesaboutwhetherthereisactuallyanotherstreamopenbythesamename.Ifthereis,itclosesthenewlyopenedstreamandtheneitherreturnsthepre-existingstream,orcausesaFILEWON'TOPENerrorifthenewandoldaccessmodesareinconflict.Thisdesigniscrufty,butIbelieveitstemsprincipallyfromtherecognitionproblemyoudon'tknowthefullnameofafileuntilyouopenit,soyoucan'ttelluntilthenwhetheryoushouldhavetriedtoopenitinthefirstplace.Itwill,ofcourse,havetobecompletelychangedwhenwegotomultiplestreamsperfile.(REOPENFILENAMEACCESSRECOGPARAMETERSDEVICEOLDSTREAM)ThisisexactlylikeOPENFILE,exceptthatitiscalledafterLOGOUT(orother``after''events)onthenameofanystreamthatwasleftopenoverexit.TheideaistomaintaintheillusionthatthefilereallywasopenoverLOGOUT,butcheckandmakesurenothingchanged.ThegenericfilesystemcodeusestheVALIDATIONfieldtotestwhetherthefilechangedbehindyourback.OLDSTREAMisthestreamthatwasopenbeforeexit,andissuppliedforthebenefitofdeviceswherethereisnopossibilitythatthefilechanged(e.g.,{CORE}),sothattheycanjustreturnOLDSTREAMdirectly.OLDSTREAMisalsoofuseforthosedevicesthathavetocheatinordertomaintaintheillusion.Thiswillhavetochangewhenwegotomultiplestreamsperfile.(GETFILENAMENAMERECOGDEVICE)Performs``recognition''onNAME.Thatis,itreturnsthefullnameofthefilethatwouldbeopenedbyOPENFILEintheindicatedrecognitionmode,orNILifthefileisnotfound.ItisnotnecessarythatOPENFILEactuallybecapableofopeningthefile(thereisnoneedtocheckprotection,forexample).UsedbyINFILEP,OUTFILEP,FULLNAME.(DELETEFILENAMEDEVICE)DeletesthefilenamedNAME,returningitsfullnameonsuccess,NILonfailure.RecognitionmodeisimplicitlyOLDEST.Localdevices,afterrecognizingthefile,shouldmakesurethatitisnotOPENP(openfilescannotbedeleted).ThisandRENAMEFILEareusuallytheonlydevicemethodsthatneedtoknowanythingaboutwhatfilesareopen.(GENERATEFILESDEVICEPATTERNDESIREDPROPSOPTIONS)EnumeratesfilesmatchingPATTERN.Returnsa``filegeneratorobject''oftheform(NEXTFILEFNINFOFN.ArbitraryState).ThisisdescribedinmoregorydetailunderDirectoryEnumeration./0 fr hsp hsbr#!t&3(),d033btb9brb:N?NCGGbtbJibrbJJb`.qj`.t`. &#'`.r`.(+,.0314l6;9=uADG;JJ`.^[+ #5'2)+.`258;nA EjFHJJ^[\tI\r\J$(r*-/.25r8<?AEG~JJ\ZJJZtZ"&XZrZ&)4*l-00ZtZ :>6ZrZ?!@@ZtZE_K@K@ZXXrX u %(+i/168J9S< >? FI+JJXWi$)'-*.058 >/@D!G;G;WtWHWrWIAJJWUEvJ %_(),?1=7";=d=dUEtUEDUErUEDFkJJUESr |!%(N*/M057z=2>AASrtSrGSrrSrH9JJSrQcQNNv (!%_)$+j-m/ 2c558(:m=??NtNE{NrNFIAJJNL8 |"$1&f*~.36,9s:CIFHJJITG\4 #&.*.3,58<A;C JJGE/EtE %#(ErE(,%-]/2Y47'; ?9AeBGHZHZEsEJJED!O  # (+5- 2 :<?ACFGHJJD!B4%{% #%*,2/2>46 89:<?B BeC}EGJJB@ > G"#%&G*.Q0#1@r@1@ =t =x==t=WW=x==t==x=!=t=""=x= *]=t=+4+4=x=/=t=0z0z=x=7=t=8=:r//:t:":r:#'*,-o1Y44:t:9:r::AEHJJ87#j7#t7#$7#r7#%(X,6.25:@i@CHJJ7#5P5Pt5P %V5Pr5P%(*.,136;Q?BE5P2cx2cr2cjK #&T).(1635o;=M?DgF*JJ2c0U "w%V'*A/3+3+0t0850r09;t>SAtDFJJ0.x.r.Z.x.%f.r.%'N*+.80p48;>@{DEIBJJ.,K,*s]# !##'^+-,.*r*.* &t &x&W&t&..&x&*&t&&x&"p&t&#M&#rK #x#$#r#$%(,)*/z14794;i=@KDLFJJ#"$``"$t"$"$r"$q$" )-/y/y"$t"$1"$r"$2X35798;?@ AXBDJJ"$ QPP Qt Q Qr Q!d&R'-7/15709'A HJJ Q~f44~t~"~r~""~t~)}~r~*-*-~t~0~r~1B~ 8t 8x88t8WW8x88t88KraKxK"jKrK#S)d+I-1388KtK;SKrK;=BC@ JJKx` xtx xrx!";%+.L 57:?BEH[IJJxtrV& "$*J**s-/5 7.8<>z@D8HJJO'! #?$'r' t xtx!-t""x *t++x1t1 r  x & r &'Y,{-06;Q<?CBC x Ji r JJ  x r X x  r <!&"d(\)-@06377 z = E- r E  q?`7(RENAMEFILEOLDNAMENEWNAMEDEVICE)RenamesthefilenamedOLDNAMEtohavenameNEWNAME.Returnsthefullnameofthenewfileifsuccessful,NILifnot.RecognitionmodeisimplicitlyOLDforOLDNAME,NEWforNEWNAME.ThegenericfilesystemcodeinvokesthismethodtoimplementthefunctionRENAMEFILEonlywhenthehostfieldsofbothfilenamesmaptothesamedevice.Defaultsto\GENERIC.RENAMEFILE,whichisalsothefunctionthatthesystemcallswhentheoldandnewnamesareondifferentdevices.\GENERIC.RENAMEFILEisdefinedtocopyOLDNAMEtoNEWNAMEandthendeleteOLDNAME.Thefollowingmethodsareinvokedforopenstreams.Theyareallrequired:(BINSTREAM)ReturnsthenextbyteofinputfromSTREAM,ortakestheappropriateactionifatendoffile.Unlessadevicehasagoodreasonnotto,itshouldcall(\EOF.ACTIONSTREAM)atendoffile/stream.ThedeviceBINmethodisactuallynotuseddirectly.Rather,everystreamhasaSTRMBINFNfield,whichisthefunctionactuallyappliedtodotheinput.TheSTRMBINFNfieldcouldthusbeusedtofakeaspecializationofthedevicedifferingonlyintheBINmethod.However,thetypicaluseofSTRMBINFNistotemporarilyoverridethedevicedefault.Inparticular,settingastream'saccesstoINPUTorBOTHautomaticallysetsthestream'sSTRMBINFNtobethedevice'sBINmethod;settingaccesstoNILorOUTPUTsetstheSTRMBINFNtobeanerror.Thisrelievesthedevice'sBINmethodofanyneedtocheckthestream'saccessoneverycalltoBIN.SomenetworkstreamstemporarilysettheirSTRMBINFNtobeaninputeaterwhentheyreceivea``clearoutput''command.Currently,allInterlisp-Dstreamshavebytesize8,soBINalwaysreturnsan8-bitinteger.CallstothefunctionBINarecompiledintotheBINopcode,whichrunsinmicrocodeonsomemachinesiftherequirementsforitaremet.Moreonthislater.(BOUTSTREAMBYTE)OutputsBYTEtoSTREAM.AswithBIN,thismethodisnotuseddirectly.Rather,everystreamhasaSTRMBOUTFNfield,whichisthefunctionactuallyappliedtodotheoutput.Settingastream'saccesstoOUTPUTorBOTHautomaticallysetsthestream'sSTRMBOUTFNtobethedevice'sBOUTmethod.ThereexistsaBOUTopcode,butthedesignisincomplete.(PEEKBINSTREAMNOERRORFLG)ReturnsthenextinputbytefromSTREAM,butdoesnotadvancethestreampointer.ThusasubsequentPEEKBINorBINwillreturnthesamebyte.Atendofstream,thedeviceshouldtakeeofactionaswithBIN,unlessNOERRORFLGistrue,inwhichcaseitshouldreturnNIL.(READPSTREAMFLG)ReturnstrueifinputisavailablefromSTREAM,thatis,ifaBINrightnowwouldsucceedwithoutwaiting.Defaultsto\GENERIC.READP,whichusesEOFPandPEEKBIN.E frIhspJjhs b5t b5xb5b5tb5b5xb5!b5tb5!!b5xb5&Gb5tb5'$b5_HrU_Hx_H%_Hr_H%k&*--_Hx_H3_Hr_H4|49<>qBCEHJJ_H]~ ~~]~t]~]~r]~{  '+f, 22]~t]~5Q]~r]~577]~x]~=]~r]~>>]~t]~A=]~r]~ACC]~x]~J]~r]~JKK]~[_|"*').0Y719>>[t[ GZ[r[GJJ[Y,sS #'.25T8=BCIAJJYXt XrX!K%=&)B+035:?=3@CEcHJJXV;%%%V;tV;5V;rV;68D=?jBBV;xV;HV;rV;IAJJV;ThxThrTh v vThxTh&hThrTh&Th P {!$`)|)--/S16P Mt''MxMMtMMJrCb H#'u'uJxJ,CJrJ-0/24 ,1?34[ItI >>IxICItID[IrIDFI6JJIG0 iG0DLpDLtDL?DLrDL!Q&k(,*1z26:?+ABBDLtDLJjDLrDLJJDLBy> %*,3.0c4G47o7oBytBy>ByrBy?iB|F)HJJBy@8$ !l#%B)c.13h55@t@8+@r@8=>3DDFJJ@>>t>(>r> &,5.278 9 @=DEJJ>={{=t==r=M))=t= =r=!# ),_.4:4:=t=;=r=-@7BGG=t=Ji=r=JJ=;-WU;-t;-"y;-r;-"$$;-t;-);-r;-*',/ / ;-t;-6;-r;-78:W>W9Zt9Z@9Zr9ZAAEJJ9Z7f !!7t7)a7r7)+Y-,/259i<[@AEJJ7552  $['s,x-/n/n2t212r22K6;<?DN2/mm/t//r/ r"(+--/t/0b/r/059=>E^G^JJ/.h !#%!'G*2*./2d5_. *t*x**t**x**t**'r'x''r''x'e'r'  t"[%J%J't'''r'(*/13c6t;;@D6H{JJ'&&t& &r&!#W%+ 0468z:?~?DEJJ&$@$@t$@)$@r$@HH$@t$@ $@r$@! )h+.=3r3r$@t$@ ;$@r$@>btb qbrb!"v$ ,.|.|btb1brb2g49<>A\FH9JJb`.6 V#%*0139`.]Jx]Jr]J(jj\ &)/>1368G<>gAEFF]Jx]JI+]Jr]JIJJ]J[t[r[[t[[r[H##[t[&[r[&n'),06467:b;>t D0[ X:tX:xX:X:tX:X:UMrxxUMxUM!FUMrUM!#J%(\*-041h1hUMtUM3UMrUM4|8gA'BEZIAJJUMSzpV%*+{- 2i48$8$SztSz;SzrSz<(??SztSzC5SzrSzCEGJJSzQ1 \#%>'<*/5:=??D2FHJJQO_!%&V(.+/OLC4LtL#LrL#|%q*R-0278 ;>K&tK&BYK&rK&BDFJJK&ISIS FtFxFQFtF((FxFFtFFxF #FtF$$FxF)^FtF*;FC)rxV"(`*--C)xC)2hC)rC)2699C)xC)>C)rC)?JBEIAJJC)A_ N A_xA_%]A_rA_%*y++A_xA_ 3UA_rA_4 4g9;D;DA_tA_ F/A_rA_FJJA_?  ?t?q?r?RR?t? )f?r?)?<? #$(+, 3s3sABFHIJJ<:W %(,M1 8Q9<: 7tZZ7x7(7t77x77t7``7x7 $7t7%%7x7*57t7+74rh#`(E(E4x4,4r4-P-1O224x474r48<?BEE4x4Ji4r4JJ42[2x2 D2r2n$&e&e2t2 2'2r226 =e@U@U2t2 Ji2r2JJ211t1v1r11 -t -x--t--x- $-t-$-*rE 9 '+06588*x*=*r*>ADGJKK*)x )r)!T#(-@/3679G?AAD-H{JJ)'>1  # *+0n11'>t'>5L'>r'>59; AC JJ'>%k[%k"3.Q!&]&]"t" /"r"036&:?5BHJKK" 9ac "k%% t . r /m3k579<?lDH9JJ }K!"%(),&149,;0=?yAQDI+JJV c %%t(Jr(* 016N9=>A?@ GJJG K $*O+/^35@; A'Gtr"k$&K -0.224b6;@E(E(tGrHoJJ Z$&+0t377t A5rAE^HJJ "" t *K r */}4  \t< \r \"Y#'*2*2 \t \00 \r \4 \t \5r @] \r \@ \ < q?`9CREATIONDATEDatewhenthefile'scontentswerecreated,asastring.Thecreationdatedoesnotchangewhenafileiscopiedorrenamed,onlywhenitischanged.WRITEDATEDatewhenthefilewaswrittentoitscurrentplaceofstorage.READDATEDatewhenthefilewaslastread.ICREATIONDATE,IWRITEDATE,IREADDATEThecreation,writeandreaddatesasintegers,suchasfromthefunctionIDATE.TYPETypeofthecontents:TEXTforfilesthatcontainonly``text''(generallymeaning7-bitascii),BINARYforallothers.NILmeansunknown.AUTHORNameoftheuserwhocreatedthefile(astring).Thefollowing``generic''attributesaregenerallyhandledbythegenericsideofGETFILEINFOifthedevice'sGETFILEINFOmethodreturnsNIL:EOLTheendoflineconventionofthestream(CR,CRLForLF).BUFFERSThenumberofpagemapbuffersforusebythestream(seedescriptionofMAXBUFFERSfieldofpagemappedstreams).ENDOFSTREAMOPActiontotakeonanyattempttoreadbeyondtheendoffile.Thisisafunctionofoneargument,thestream.Thefunctioncancauseanerror,orreturnavalue,whichisinterpretedasavaluetoreturnfromBIN.ThedefaultENDOFSTREAMOPcausesanENDOFFILEerror.ACCESSAnatomdescribingtheaccessmodeofthestream(INPUT,OUTPUT,etc).Thisissogenericthatitishandledbeforethedevice'smethodeverseesit.BYTESIZE,OPENBYTESIZEThesizeofbytestransmittedonthestream.Always8thesedays.(SETFILEINFONAME/STREAMATTRIBUTEVALUEDEVICE)SetsthevalueofthespecifiedATTRIBUTEofNAME/STREAMtobeVALUE.ReturnsTifsuccessful,NILifunsuccessful,orforattributesitdoesn'tknowabout.ItisnotgenerallyrequiredthatSETFILEINFOrecognizeanyattributesatallNILLisaperfectlygoodfillerforthisslot.MostdevicesrecognizenomorethanTYPEandCREATIONDATE(ICREATIONDATE),andeventhosearenotveryimportant,asmostapplicationssetthoseattributesinthePARAMETERSargumenttoOPENFILEwhencreatingafile.ATTRIBUTE=LENGTHimpliesactuallytruncating(orlengthening)thefile;however,theSETFILEINFOneednothandlethisitselfifitreturnsNIL,thenthegenericfilesystemwillattempttousetheSETEOFPTRmethodinstead.Thefollowingoperationsareonlyrequiredofrandomaccessstreams.Theydefaulttothefunction\IS.NOT.RANDACCESSP,whichcausesa``Streamisnotrandaccessp''errorwhencalled.(GETFILEPTRSTREAM)Returnsthecurrentfilepointer(byteposition)inSTREAM.Thefilepointeriszerowhenthestreamisopened(exceptforACCESS=APPEND),andisincrementedbyoneforeachbyteread.@ \ frIhspJjhsbt brb"&i*i-06Y9?`AZBGGHJJb`. %c(m*/<2367Z;=AC"FIJJ`.^d $M^d[to[r[ $&(+i/1k37;<A&[YtYrY $&(+i-0YVxt VxrVx{{VxtVx 'VxrVx((VxtVx0 VxrVx0&VxT^ &T),/3`5:=?CEzJJT^Rt!RrR"\ROtDNKstKsrKs!#D%u(@+/1459KsHUN a %^'-p246;>S??HtH I6HrHIJJHFFtF FrF!G&!**FtF-)FrF-FD teD rD  u"$' -/x156cD tD 8D rD 88D tD <D rD > D tD ?D rD @D AetAerAe %'-`24N68;?BZ I7JJAe?t &2?r?&)+ 285?K@C+DGmGJJ<; #%y')/2<67I:?UAEUG&JJ;9N#$(,- 467;D<@DRDR9Nt9NF9Nr9NGHJJ9N7{"C"C7{t7{ -.7{r7{-13S3S7{t7{694<7{r7{<@@@7{4t4r4 # * ,a0b4+58-<= 4t4A=4r4BB4t4G4r4GJKK43 !#("*+-'2C6b8=B]E3GI 30ctF &Z0cr0c'*-/g3! :<?4D!DIeJmJm0c.!&$". +St +Sx+S +St+S+Sx+S% +St+S%%+Sx+S)+St+S**+Sx+S/1+St+S0+S(frS""(fx(f)(fr(f){++(fx(f 3(fr(f4J577(fx(f;(fr(fV t xt #rL'$z(-// #x #4m #r #5^58;]@5ADHJJ # YW!f!f Yx Y% Yr Y&>'' Yt Y- Yr Y.)01 9;n=?BEH Y q?`710Althoughthisoperationisonlyabsolutelyrequiredforrandomaccessstreams,itisdesirabletosupplyitforotherstreamswherepossible.Forexample,whenreadingafilesequentiallythroughPupFtp,thestreamcancountthebytesastheygobyandthusgiveanaccuratevalueforGETFILEPTR.Ifastreamhasnoideaatallofposition,itcanmakeitsGETFILEPTRbethefunctionZEROandtherebyatleastavoidbreaksfromcodethatcallsGETFILEPTRcarelessly.(GETEOFPTRSTREAM)ReturnsthefilepointeroftheendofSTREAM,i.e.,thefilepointerthatGETFILEPTRwouldreturnafterthelastbyteofSTREAMisread.SameastheLENGTHattributeforastreamthatrepresentsafile.Ofcourse,non-randomaccessstreamsmayhavenoideawheretheendis,andcausinganon-randaccessperrorisperfectlyacceptable.(SETFILEPTRSTREAMBYTENUMBER)SetsthefilepointerofSTREAMtobeBYTENUMBER.ThespecialvalueBYTENUMBER=1meanstheendofthestream;othernegativevaluesareillegal.SETFILEPTRbeyondtheendofthestreamispermissible,butithasnoimmediateeffectbeyondchangingthelogicalfilepointer.AttemptingtothenBINcausesanEOFerror.AttemptingtoBOUT(forafileopenforwrite)shouldextendthefile,sothatitseofisimmediatelybeyondthenewlyBOUTedbyte.AswithGETFILEPTR,thereisnorequirementthatthisworkonnon-randomaccessstreams,anditmaybecompletelyimpossibleonsomeofthem.However,forthosenon-randomaccessstreamsthatperformGETFILEPTR,itispossibletofakeSETFILEPTRforvalueslargerthanthecurrentfilepointerbyskippingsomenumberofbytesinthefile,e.g.,byperforming(RPTQ(DIFFERENCEBYTENUMBER(GETFILEPTRSTREAM))(BINSTREAM)).TherearesomeapplicationsforwhichforwardSETFILEPTRisalltherandomaccessthatisactuallyrequired,soitisnicetobeabletoaccommodatesuchapplications.(BACKFILEPTRSTREAM)BacksupthefilepointerinSTREAMbyonebyte.Functionallythesameas(SETFILEPTRSTREAM(SUB1(GETFILEPTRSTREAM)),butmaybepossibleonnon-randomaccessstreamsbymaintainingaone-characterbuffer,whichisallthebackingupthisoperationisformallyrequiredtoperform.IbelievethemainuseforthisisinREAD,whichneedstobackupthestreamonecharacterwhen,forexample,itreadsabreakcharacterterminatinganatom.(SETEOFPTRSTREAMLENGTH)ChangesthelengthofSTREAMtobeLENGTH,i.e.,``sets''itsendoffilepointer.Thismayrequirelengtheningortruncatingthefile.Usedbythefunction\SETEOFPTRandbySETFILEINFOforattributeLENGTHwhenthedevice'sSETFILEINFOmethoddoesn'thandleit.Thefollowingthreefieldsareplaceholdersforpossiblefutureextensions.Thesefieldsarenotcurrentlyusedatall:(LASTCSTREAM)ReturnsthelastcharacterreadfromSTREAM,i.e.,thelastbytethatwasBINed,asacharacter.LASTCiscurrentlyimplementedviaBACKFILEPTR.H Y fr hsp LhsbrRz $ *02W7y;@B2CIAJJb`73 $|)*W,26%:<>L EJJ`7^mL $&*i,K/136:= ?DDHJJ^m\t \r\i&!$&')&*,.~45w8 ;==\t\ F \r\FHJJ\ZZtZ4ZrZ "P%F(,073N588ZtZ A2ZrZA GpZ Wt 11WxWWtWWTr ."`$&w&wTxT+ETrT+.^027e::TtT BkTrTBFJJTRI8RxR!RrR"#Q&'*,5.t.tRtR3~RrR39P;m136m8<:; CHJJ@>cc>t>>r>>>>;~~;t; ;r;" #Z%B ,/25x7` ?C H8JJ;:g 5 #%) *.k.46:a BEJJ:8RG8Rt8R 8Rr8R!"$F)l+--8Rt8R 6U8Rr8R68<@CF(JJ8R6h!%*,0258 F6F66t6K@K@64 4x4 "4t4# --4x424t45M994x4>b4t4@4r4@A>E$G]JJ42 ,#1#12t2 +2r2,-Y/01w6~:r='>{CuI+JJ216C %( 01 -t -x--t--*rP ""*x*'^*r*(*#,0x1 9<;?\A,A,*t* K@K@*) x_) t) 8E %\%\) x) **) t) +) r) ,.13~8:j BEJJ) '6 e $[)-4.03[8:=CEpJJ'6%l}bE"%([*,/9022%lt%l5b%lr%l69=?>B]DHFJJ%l#$R%z()-3D :o<2?# \t 11 \x \ \t \ \x \ \t \ \orFboxo"oro#9$&&oxo+roro,5.24Q68:?@DCAF)JJo  " $%(*^,11t :Mr:=???t HRrHJJtrQ!%%t /5r/4g8=J>w X x#%*. 56 9=?BGJJX  _ G QtQxQQtQQdr1 #'-'-dxd+drd,/w14a7v:I<<dtd?drdACD JKKd t r Z $"&1&1 t /n r /  q?`11(FREEPAGECOUNTHOST/DIRDEVICE)IntendeduseistoreturnthenumberoffreepagesonHOST/DIR.MaybefoldedintoageneralGET/SETdevice/directoryinfooperation.(MAKEDIRECTORYHOST/DIRDEVICE)IntendeduseistocreateanewdirectoryHOST/DIR.TheremainingfieldsintheFDEVareforbufferedandpage-mappedstreams,andareignoredfornon-buffereddevices.Thesefieldsaredescribedinseparatesections.StreamsThefollowingfieldsareusedbyallstreams:DEVICEPointertothisstream'sFDEV.FULLFILENAME``Full''namebywhichthisfileisknowntotheuser.Shouldbeanuppercaselitatom,fullyqualifiedsothatgivingthesamenamebacktothefilesystemshouldproducethesamefile(totheextentthatthedevicecansupportsuchuniqueness).IsNILforunnamedstreams.FULLNAMEAccessfield.IsthesameasFULLFILENAME,unlessthatisNIL,inwhichcaseitisthestreamitself.ThisavoidsthecircularitythatwouldresultiftheFULLFILENAMEfieldcontainedthestreamdatum.NAMEDPAccessfield.IsTifthestreamsisnamed,i.e.,itsFULLFILENAMEisnon-NIL.ACCESSBITSContainsanumericcodedescribingwhataccessmodethefileisopenfor:thereareread,writeandappendbits.ThisfieldisusuallyaccessedindirectlyviatheACCESSfield.However,therearemacrosforreferringtoparticulartypesofaccessusingmoreefficientbittestoperations:(OPENEDSTREAM)ACCESSisnotNIL.(READABLESTREAM)Readbitison:ACCESSisINPUTorBOTH.(READONLYSTREAM)Onlythereadbitison:ACCESSisINPUT.(APPENDABLESTREAM)Appendbitison:ACCESSisOUTPUT,BOTHorAPPEND.(APPENDONLYSTREAM)Onlytheappendbitison:ACCESSisAPPEND.(DIRTYABLESTREAM)Appendorwritebitison:ACCESSisOUTPUT,BOTHorAPPEND.Yes,thisisoperationallythesameasAPPENDABLE,giventhefourpossiblevaluesofACCESS.(OVERWRITEABLESTREAM)Writebitison:ACCESSisOUTPUTorBOTH.(WRITEABLESTREAM)Writebitison,orappendbitisonandfileisatEOF.Avoidusingthisone,it'salittlestrange./ frIhspJjhs b5t b5xb5mb5tb5DDb5xb5!b5tb5"b5_Hrb3"S'u)%+/11_Hx_H7_Hr_H8]8<=B.DFJJ_H]~ !+# )]~ ZAt ZAxZAmZAtZADDZAxZA!ZAtZA"ZAWTr=B "(q(qWTxWT.QWTrWT.WT S !StS SrS #&),/$ 7=@CVHJJS R  d6 &(X-2tR MvMrMM I {%2#I FktFkrFk/Q$$FktFk(@?~B=3t3D3r3E3 /t Z/r//"#& -c048; =u>BXEHJJ//- %() ,/D05Q: @CE_E_-t-Ji-r-JJ-/+! $&+`-34 :><?CG]JJ+/*UC 'A*/'4t'4x'4"'4t'4#'4r'4'''4t'4,'4r'4-.X00'4t'43#'4r'43'4/$Gt$Gx$G$c$Gt$G%:$Gr$G'+(-.T00$Gt$G5$Gr$G67E7E$Gt$G;x$Gr$G;=f=f$Gt$G@$Gr$GA$G/!Zt!Zx!Z$c!Zt!Z%:!Zr!Z'*-+023C55!Zt!Z:!Zr!Z:<4<4!Zt!Z@g!Zr!Z@!Z/mt !C!Cmxm&mtm&mrm',.02Q2Qmtm7[mrm788mtm=mrm>>mtmBmrmB_CCmtmHmrmI\m/t !C!Cx&t&r'*-+1357b7bt>tC rCi/t l lx%:t&r'-.2J4i58Z8Zt=dr=?\?\tDfrEFEFtHrHJJ't,r---s0D2H3V 9;>_? GJJ')y+/2488r8/ t ## x ( t )m r ,0_2M355 t : r ;><|<| t A r ACtCt t F r G- /t l lx%:t&r'+-/_138:<\>xADCECFJ~JJ' I+/#14j6n7k:j> I q?`12ACCESSAccessfieldforreferringtotheACCESSBITSfieldsymbolically.ItsvalueisoneofthelegalvaluesoftheACCESSargumenttoOPENFILE:INPUT,OUTPUT,BOTH,APPEND;orNILwhenthestreamisclosed.ReplacingthisfieldhasthesideeffectofsettingtheBINABLE,BOUTABLE,STRMBINFNandSTRMBOUTFNfieldsappropriately(fromthecorrespondingdevicefields,ortovaluesconsistentwithnoaccess).USERCLOSEABLEFlag,trueifthestreamcanbeclosedbyCLOSEF.DefaultisT,butisNILforsuchthingsasdribblefilesandtheterminal.USERVISIBLEFlag,trueifthestreamistobelistedintheresultof(OPENP).DefaultisT,butisNILforsuchthingsasdribblefilesandtheterminal.BINABLETrueifBINmicrocodecanbeused.NormallysetautomaticallyfromFDBINABLEwheninputaccessisset.BOUTABLETrueifBOUTmicrocodecanbeused.NormallysetautomaticallyfromFDBOUTABLEwhenoutputaccessisset.EXTENDABLETrueifBOUTcanextendthebufferwhenCOFFSETreachesCBUFSIZE.Obsolete.STRMBINFNFunctioncalledbyBIN.ThisisnormallysetindirectlyasasideeffectofsettingtheACCESSfield.SettingACCESStoaninputaccess(INPUTorBOTH)setstheSTRMBINFNtobethestream'sdevice'sBINmethod.SettingtoanyotheraccesssetstheSTRMBINFNtobea``filenotopen''trap.STRMBOUTFNFunctioncalledbyBOUT.AswithSTRMBINFN,thisisnormallysetindirectly(fromthedevice'sBOUTmethod)asasideeffectofsettingtheACCESSfield.OUTCHARFNFunctioncalledtooutputasinglebyte.ThisislikeSTRMBOUTFN,exceptforbeingonelevelhigher:itisintendedfortextoutput.Hence,thisfunctionshouldconvert(CHARCODEEOL)intothestream'sactualendoflinesequence,andshouldadjustCHARPOSITIONappropriatelybeforeinvokingthestream'sSTRMBOUTFNtoactuallyputthecharacter.Defaultsto\FILEOUTCHARFN.TheOUTCHARFNforthedisplayadditionallyworriesaboutsuchthingsasECHOCONTROL.CHARPOSITIONCurrenthorizontalcharacterpositioninthestream.Incremented(andresettozero)byOUTCHARFN.UsedbythefunctionPOSITION.LINELENGTHMaximumlinelengthofthestream,incharacters.UsedbythefunctionLINELENGTH.Defaults(atcreationtime)tothevalueoftheglobalvariableFILELINELENGTH.EOLCONVENTIONThestream'sendoflineconvention:themannerinwhich``endofline''isencodedonthisstream.Thatis,outputofanendofline(functionTERPRI)producesthestream'sendoflinesequence,andoninput,thestream'sendoflinesequenceisconvertedto(CHARCODEEOL)byREADC.Thisisnotnecessarilythesameasthewaythatendoflineisencodedintheactualfilewrittenby,say,afileserver.Forexample,LispmightopenastreamtoaTenexfileserverwithEOLCONVENTIONofCR,whiletheservermightchoosetotakeeachoftheCRsinthestreamandactuallystoreaCR,LFsequenceinthephysicalfile.> I fr hsp Lhs btbrb/sw & '))btb 2,brb25 ==?C?DGHJJb/`.NU"#"#`.x`.&`.r`.'-..`.t`.5H`.r`.6"6"`.t`.:U`.r`.;;`.t`.@`.r`.@@`.t`.D-`.r`.DD`.t`.I`.r`.JJ`./^[^[t^[V^[r^[N!%'%++2;47:6Z WDt WDrWD/!8%('*.90000WDtWD5:WDrWD66;<ABBWDtWDEWDrWDEGJJWD/Uq!/#&v(-Uq Rt 1RrR/6l $&#')k,.i04:55RtR;RrR@ (!&@(+-2P-tP-3P- L//LrLLtLLrL%(f*d..46 ?hBBLtLJiLrLJJL/J/" #K%?J Got//GorGosGotGoGorGo&(*d-.M4^6c >BBGotGo JjGorGoJJGo/E"$&E B+t //B+rB+\B+tB+B+rB+C!%(,//B+tB+5B+rB+5::B+tB+ABB+rB+ABIGB+ >t>r>/  "">t>%q>r>&F&)+:03 9&:;>BD6HJJ>/@@6@DSHNJJ; /98``98t98 98r98!G"$%(q*.1d98 5t Z5r5/  ""5t5&I5r5' '),,5t54K5r55#79">@ GJJ5/3`PP3t3!3r3"'W(),~0158 8 3t3=3r3=m@r3 0qt0qr0q/ ",&m'k+'.`.125`5`0qt0q =0qr0q>wBDHDJJ0q/.!9"(+E.43238;AXFJJ./,t##,r,#&(.82<469m?BiFJJ,/+t !C+r+! *.K360;i;i+t+ C+r+DCEJJ+/). "/"($))).t). 5).r).6_699).t).A9).r).ACF@JJ)./'[ #%&)-/A/A'[t'[ 8~'[r'[8'[ #t #r#/3 "(E-[.156 =@DEHJJ#/"t"r"m#*$'),p,p"t"3("r"3" t Zr/ 3$=%',. 448e:3RDFJJ/: K!#/'a)-11:t: ;:r:5>5:t:?:r:@DFJJ:/gR #&(9*m*mgtg,grg,.047=A5EH8JJZ/Y !n#)N- 45:Y<0 C"DEIAJJY/WD:WDtWD!WDrWD!i$ ''WDtWD(~WDrWD(*-/ 7G7= >>WDtWDF(WDrWDFJJWD/Uq9UqtUq X"&9UqrUq&)Uq Qt ZQrQ/#n)/03T68x:=y@CE/GJJQ/P$0!$F$FP$tP$ ,P$rP$-L236z99P$tP$ DP$rP$EcJJP$/NQ"(B(+.1f36`9;<@FHJJNQ/L s sLtL%}LrL&+..LtL 7LrL7:<AGJJL/Jt JrJ !d!dJtJ%JrJ& '))JtJ 2[JrJ24v6;!>BBJtJGJrJHJJJ/H"C#% ,-G-GHsH/16P79;?A!BFJIJJH/G!#%nGrG%tG CtCrC/>a #?%((CtC+sCrC+.p.pCtC1CrC22688h=?W@A*D"G0H{JJC/A<  #y%+>,;./36/9=>J@{C\EGI\JcAtAJiA >Y //>Yr>YJS"E$)-G/2X8(8(>Yt>Y @>Yr>YABIAJJ>Y/JJ9 /79| #_&q((79t79 279r792279t79879r799x9?D@@79t79 J79r79JJ79/5f"2'c) 1u67:H< FJJ5f/33z3'-3r3-x3 0 t0 r0 /"O%%'4){+I+I0 t0 20 r0 220 ,t ,r,/#%k'),-`.2F3O8;A$ HJJ,/*O"()], .M 4s6 ;?t@CqEJJ*/( %4't,.[0278+9? DDFJJ(/')."%u(N+H-1~3479s:s:s')t')>')r')?AD$H$JJ')/%VK J!%) +,/488_>f?DOEJJ%V/# u"'*./38;)>BLFjHNJJ#/! #U')*.,06;?1@CsEJKK!/j#%=(1+0,04D59;T>HBPCG<IJJ/.i!%(*,-02/5 <+. /5 n"Y%,(*.36:];=C@EJJ/tro#&(+.1@4 9+<>AFIFJJ/ ;t#$(*+2q59=?BHJJ /V $g%(h+a+aVtV 6LVrV778;8=?.BSCHJJV/EU"+$(Z*- t;r,"D$%'h .11t <r=W>BOCVEHCJJ/?<x"%(+; 25K:=?BkEHJJ?/ ux  ur uv%'' ut u- ur u.835:H?kBDUFJJ u/ t%v r &L   q?`14F1,F2,F3,F4,F5Pointerfieldsforprivateusebythestream,tomaintainstream-specificstateofconcernonlytothedevice.StreamclientsthatwishtohanginformationonastreamwithoutregardtowhatkindofstreamitisshouldusethefunctionSTREAMPROP.FW6,FW7,FW8,FW916-bitwordfieldsforprivateusebythestream.DIRTYBITSObsolete.EXTRASTREAMOP?BufferedStreamsBufferedstreamsareonesthatconstrainthemselvestoobeyasetofconventionsthatmakeiteasyforanagent(e.g.,microcode)toperforminputoroutputonthestreamwithoutknowingaboutthedetailsofthestream'sphysicali/o.Thestreammaintainsa``currentbuffer''andtwoindicesintothatbuffer,theoffsetofthenextbyte,andtheoffsetoftheendofthebuffer.Aslongastheformerindexislessthanthelatter,thestreamguaranteesthatthebytesinthebufferbetweenthoseindicesarethetruecontentsofthefile/streamstartingatthecurrentfilepointer.Advancingthefirstindexeffectivelyadvancesthefilepointer.Whenitreachesthesecondindex,astream-specificoperationiscalledto``refill''thebuffer.Thefollowingfieldsareusedbybufferedstreams:COFFSETByteoffsetinthebufferCBUFPTRofthenextBINorBOUT.CBUFSIZE``Size''ofthecurrentbuffer,i.e.,byteoffsetthatisonebeyondthelastbyte.CBUFMAXSIZEForoutput,themaximumsizethebuffercanbewrittento.IfCOFFSETreachesCBUFSIZE,butCBUFSIZEislessthanCBUFMAXSIZE,thenthebuffercanbeextended.CBUFPTRPointertocurrentbuffer.MustbevalidifCOFFSETislessthanCBUFSIZEandBINABLEorBOUTABLEistrue.Itisnotnecessarythatthis``buffer''beanythingotherthansomechunkofmemory,aportionofwhichcontainsinterestingdata.Thus,thebytesfromoffsetCOFFSETtoCBUFSIZEmustbevalid,butCOFFSETneednotstartatzero,norneedCBUFSIZEorCBUFMAXSIZEcoincidewiththeendoftheunderlyingstructure.CBUFDIRTYFlag,trueifcurrentbufferhasbeenwrittento.Ingeneral,thedevicehassoleresponsibilityforsettingCBUFSIZE,CBUFMAXSIZE,andCBUFPTR;genericcodedoesnottouchthose.ThefieldsCOFFSETandCBUFDIRTYcanbechangedbygenericstreamclientsaswellasbydevice-specificcode.Forexample,codethatsimulatesaBINincrementsCOFFSET;codethatwritesdirectlytothestream'sbuffersetsCBUFDIRTYtrue.Thefollowingmethodsaredefinedfordevicesimplementingbufferedstreams:(GETNEXTBUFFERSTREAMWHATFORNOERRORFLG)[Devicemethod]CalledwhenSTREAMneedstohaveitsbufferfixed,i.e.,thestateofSTREAMissuchthatBIN(WHATFOR=READ)orBOUT(WHATFOR=WRITE)cannotproceed.Thismethodshoulddo&L fr hsp Lhs bt brb R Rbtbbrbbtb^brbbtbbrbllbtbbrbr/`!u%(3*,>02b7ADEJJb/`.;0"#8',.136 >l@fAEJJ`./^dO"$()+//y139898^dt^d A^dr^dA^d Zt yZrZ ) )ZtZZrZ^^ZtZZrZZtZZrZ/O!#(N*,c.2ZtZ344ZyZ4Z WptWprWp/Wp St SrS/S Oavc(OarOa.Oa KJty! (*-J.K0>1 91;?]@CbEuG;JJK I 4 ;  B$&(-2 7;I=AC_EJJI H%#0Q b%*-/4/69> @NCEGJJH% F[ ON  f %2%'*,b.3:68X:=@ND-FJJF[ D 7kW %)A-/2 4:;= DIVJJD B =AG!$(? .4v69>>BCHJJB @UHE_"U#'Y( -Y/3@ = {%2"j'V= :t//:r:0K!|%{%{:t:+\:r:+-?/p2Q2Q:t:4:r:5.66:t:: :r::}: 6t//6r6M #'*^-?03y474;>@oCU6 3't //3'r3'!^'*-E14=6N;=C=??3't3'Em3'r3'FJJ3'/1Tt1Tr1T!!1Tt1T(1Tr1T)w+4.111Tt1T :1Tr1T;?sB#FHJJ1T/// ,t//,r,"'p(+-1X22,t,8,r,9\:=@@,t,G,r,H8JJ,/*=t*=r*=l*=t*=%*=r*=&']*m*,-Z/58.: @AGRJJ*=/(jJ!#)[*|/L04:P @DKDHJJ(j/&!!&t&'&r&'))&t&0I&r&0459;;&t&A&r&B?EGJJ&/$'##$t$*;$r$+ -C-C$t$ 6$r$7e=-@CcFyHJJ$/"  #|" t//r|1d"&)C,q02rt2x r B] $&+-+-t1r22t ;r<?\?\tE=rF)JJ < ]+ _ _A, H8JJ`7^dji #&w&w^dx^d+E^dr^d,y16%^d[@}I[x[[r[$ [t[$D[r[%%[t[ /[r[0O44[t[5[r[67<?V@@[x[Ec[r[EGIWJJ[Y%XYxY }YrY "*#&4'*h*hYtY 5SYrY5: <BVDFJJYW a aWtW )WrW).04 66<>%>%WxW FWrWFrGJJWVt |VrV "&&VtV)VrV)l 1V Rt RxRtR22RxR RtR!RrR@EJlRtRObROry").22OxO7IOrO8Y<>3@EI6JJOMx_MrMMtMzMrM 5!x '+.5.5MtM4MrM4s7y8 >?BB2CuFH#JJML* #S%)i-1v14:W;>QA6B JJLJ9J9tJ9 J9rJ9!%%''r+.0a258?:??J9tJ9GPJ9rJ9GJJJ9HfHfE{U!$E B NNBtB 9BrB\\BtB-BrB..BtB :BrB;;BtB GmBrBH8JJB @>t@>r@>j!5#%+C036 <?AHJJ@> >kt y>kr>k R R>kt>k3>kr>k  >kt>ki>kr>kCC>kt>k$>kr>k!X!X>kt>k(>kr>k(,23/4:=BB>kt>kJ>kr>kJJ>k < A! #%N+D/2Q2Q8<@BDJJ' &%b&% "t"x"X"t"/"r"DL Jl"t"Ob"r5v (A*n 2j7x:>AFVJKKL(!%Z%Zt,r--t 6r66t>dr?&?&t JrJJ*t *r*;;*t* *r*!$(+.44*t*7%*r*8j8j*t*;*r*= = *t*B*r*D0D0*t*J*r*JJ*WtIWrWWtWWrWWtW"WrW##WtW ,WrW--WtW 6WrW88WtW @WrWBBWtWJWrWJJWt rt #r$&&t /r06  W C[#%+1@3=8|:=sBDdF)JJ @ }%ss@t@#@r@$@ t 11xtx [t!2!2x&lt'Cr@EJltOb r55 x  r ` "%(M(M x - r .;.1G37:;G;G x B r C*F|HJJ  Mx[x x # r #$()- 48)99 t AA r B~DHJJ  q?` 16exactlyonepageisread,oritisalistofsuchbuffers.READPAGESreturnsthetotalnumberofbytesread.Ifthelastpagereadisnotafullpage,READPAGESshouldzeroouttherestofitsbuffer.READPAGEScanassumethatthebuffersarepage-aligned,althoughtheyneednotbeconsecutive.(WRITEPAGESSTREAMFIRSTPAGE#BUFFERS)[Devicemethod]WritesdatafromBUFFERSouttoSTREAM.ThefirstpagewrittenisFIRSTPAGE#.BUFFERSisaswithREADPAGES.NeitherREADPAGESnorWRITEPAGESaffectsSTREAM'sfilepointerorendoffile;thosearemanagedbyhigher-levelpagemappedroutines.WRITEPAGESmight,however,wanttolookatSTREAM'sEPAGEandEOFFSETfieldsifitneedstotakeanyspecialactionaroundtheendofthefile.Itispossible,fornoparticularlygoodreason,forREADPAGEStogetcalledforapagebeyondtheendoffile;infact,thisstandardlyhappenswhenwritinganewfile.TheREADPAGESmethodinthiscaseshouldjustclearthebufferandreturnzero.(TRUNCATEFILESTREAMPAGE#OFFSET)[Devicemethod]TruncatesSTREAMsothatitsendoffileisPAGE#,OFFSET,whichshouldbedefaultedtoSTREAM'sEPAGEandEOFFSET.Canbeusedtoeithershortenorlengthenafile;iflengthening,thefileshouldbepaddedwithnulls.Usedby\PAGED.SETEOFPTRand\PAGED.FORCEOUTPUT.Asofthiswritingtherearestillbugsinthiscodeincertainfunnycases,suchaswhenyouSETFILEPTRbeyondeofandthenBOUT.Thefollowingfieldsofastreamaremeaningfulforapagemappeddevice.Thegenericpagemappedcodesmaintainthemasoperationsonthefileareperformed,buttheyshouldallbeinitializedappropriatelybythedevice'sOPENFILEmethod:CPAGEForpagemappedstreams,thecurrentpagepositioninthestream.TogetherwithCOFFSET,thisconstitutesthestream'sfilepointer.Thedevice'sOPENFILEmethodshouldsetCPAGEandCOFFSETtozero,exceptforfilesopenedwithaccessAPPEND,inwhichcasetheyshouldbesettotheendoffile.EPAGE,EOFFSETForpagemappedfiles,thepageandbyteoffsetoftheendoffile.Notethatthisisthelogicalendofthefile;itneedhavenothingtodowiththephysicalendoffile,exceptthatwhenafileisclosed,thedeviceshouldseetoitthatitslogicalandphysicalEOFsarethesame(normallyseentobytheTRUNCATEFILEinsideof\CLEARMAP,below).Infact,asatypicalfileisbeingwritten,EPAGEtendstostayseveralpagesaheadofthephysicalendoffilebyvirtueofthefactthatpagesarebeingbufferedbeforebeingwrittenout.BUFFSForpagemappedstreams,apointertothestream'sBUFFERchain.InitiallyNIL(nobuffersallocated).Thedeviceusuallyhasnodirectinterestinthisfield.MAXBUFFERSForpagemappedstreams,themaximumnumberofbuffersdesiredinthestream'sBUFFSchain.IfthecodeneedsanotherbufferandtherearealreadyMAXBUFFERSbuffers,itwilltrytorecycletheleastrecentlyreferencedbuffer.Defaultsto\STREAM.DEFAULT.MAXBUFFERS.TheusercanchangethisfieldforanopenstreambycallingSETFILEINFOwithattributeBUFFERS.J  fr hsp Lhsbr% p!"$P%u')^,12 2 btb9brb:>AD:I6JJb`.(&!$&j(*,0?0?`.t`.7`.r`.8X<?BQDGYIJJ`.^[)^[t^[R^[r^[ %e(F*/~1 :[@&CIFHJJ^[\ \ Yt YxYYtYYxY !2YtY" " YxY'CYtY(YrY@EJlYtYObYV*r,,V*xV* fV*rV* #?$$V*xV*)V*rV**w*-0y38N99V*xV* A/V*rV*ABpBpV*xV*GV*rV*HI@JJV*T`||T`tT` T`rT`hT` PPtPPrPPtP "PrP"&&PxP+PrP-/w4<68:s=U@CGHJJP O  UOtO (ROrO(-G3168];=.=.OxOAOrOCoCoOtOGOrOH8JJO M@tM@rM@~SPS$ ?#'+03667:n=P=?A#FHJJM@ Km ]00KmtKm#KmrKm$m&B(,/3039;>f@FCOE$HOJJKm I s>!$$v'"'"ItI.IrI/ 35m7:>AiDFJJI G }|UG DVt DVxDVDVtDV[VxDVDVtDV Z ZDVxDV$DVtDV%DVrDV@EJlDVtDVObDVAirAixAiAirAi} !$]%())k)kAixAi-AirAi.G.GAixAi2AirAi3a7B;=WC=DDAixAiIAirAiJJAi?t?r?D?t??r?0"$':(,13g9:*=>a F.HJJ?=bQ!"3%'m'm=t=4=r=5977=t=F=r=GGG=s=IsJJ=<6R "%s&*O-v0p24=7'9F @wDXF1HPJJ<6:|:|r:| :| 7  r$G '+)`* 277:f?$ G'JJ7 5A L!# *-30'46X8. >` FHJJ5A 3w3wt3w3wr3w3w /t'/r// "1'*(/279>.*t.*Eh.*r.*EJJ.*/,W,Wt,W!,Wr,W"=$$,Wt,W*,Wr,W+1,04G6o9F> AEE,Wt,WJ,Wr,WJJ,W/*L"-&w(:*)+-0c14-* 't'r'/ !$'*A,/3|57\9;>7>ADG/HH''JJ'/%@u%@r%@r"$&)b,13/5"8(:t?BNCFJJ%@/#c "7&(-1s35E698:?7AGJJ#c/!d%)($)+--!t! 7!r!8M<-==!t!EV!r!FJKK!/JR"$&+)..t2r3M68^;?uCFHJJ/A!#t%y)w+9-0W3-79]=/BG&JJ/)) t'r/ !'(B-.16H6Ht;Rr;?@VEkEktGrHpJJ/ ""m%)*-/15{:);>A  tt Ztrt/ "')057<~A`C*EJJt/tbr s!$R'+t0z47[:=4BBt JirJJ/Y!h#& + -1X6 >CCIAJJ/t-r..157<?BEXG~JJ/ 1p>!q!q 1t 1 * 1r 1+-3O3O 1t 190 1r 19 1 q?`-17MULTIBUFFERHINTFlag.Forpagemappedstreams,isahinttothepagemapcodethatthedevicepreferstotransferdatamorethanonebufferatatime.Ifthisflagistrue,thepagemapcodetriestowriteout(WRITEPAGES)morethanonebufferatatimewhentheopportunityarises.Asimilarimprovementisplanned,butnotimplemented,forreadingmultiplebuffersatatime.Thefollowingfunctionsareofuseforpagemappeddevices:(\PAGED.FORCEOUTPUTSTREAMWAITFORFINISH)[Function]ThisfunctionimplementstheFORCEOUTPUTmethodforpagemappedstreams:itcausesanydirtypagestobewrittenout(usingWRITEPAGES),thencallstheTRUNCATEFILEmethodtosettheendoffile.ThisfunctionisnormallyinstalledastheFORCEOUTPUTmethodbythefunction\MAKE.PMAP.DEVICE.However,thedevicecanoverridethisdefault(bysupplyingitsownfunctioninthatfield),inwhichcaseitmightwanttocallthefunction\PAGED.FORCEOUTPUTexplicitlyaspartofitsmorecomprehensiveFORCEOUTPUTmethod.Thereisanunpleasantnessintheimplementationofpagemappeddevicesthatstemsfromthefactthatoriginallyalldevices(thefewthatexistedinthedistantpast)weremadetosupportthePMAPpackage,ameanswherebyaprogrammercouldgetdirectaccesstothebuffersofafile,muchasonecanwiththePMAPJSYSinTenex.Asaresult,thebuffersusedbypagemappedstreamsaresetupinaspecialmannersothatthegarbagecollectorcantellwhentheusernolongerhasaccesstoaPMAPbuffer.ThePMAPpackageisbeingphasedout.Thisisallexceedinglycrufty,andisoflittleconcerntothedeviceimplementer,exceptforthefactthatitrequiresthatthebuffersbeexplicitlyreleasedwhenastreamisclosed;thebuffersarenotautomaticallycollectedwhenthestreamisdropped.(FORGETPAGESSTREAMFROMPAGETOPAGE)[Function]``Forgets''pagesFROMPAGEthruTOPAGEofSTREAM;i.e.,removesthosepagesfromthesetofpagesbeingcurrentlybuffered,andfreesthebufferstheywereoccupying.IfFROMPAGE=TOPAGE=NIL,forgetsallpages,andreleasesallofSTREAM'sbuffers.(\CLEARMAPSTREAM)[Function]PerformsaFORCEOUTPUT(ifSTREAMisopenforoutput)followedbyaFORGETPAGES.Thisisthestandardactionthatshouldbetakenbyapagemappedstream'sCLOSEFILEmethod.DirectoryEnumerationThissectiondescribeshowdirectoryenumerationworkswhatyouneedtoknowinordertoimplementtheGENERATEFILESdevicemethod,andwhatyouneedtoknowasaprogrammertryingtoenumerateadirectoryviaanythingmoreelaboratethanthefunctionDIRECTORY.Thegeneralideaisthatthedirectoryenumerationcodeisgivenapattern,anditreturnsageneratorthat,eachtimeitispoked,returnsanotherfilenamematchingthepattern.Inaddition,thegeneratorprovidesahandleforgettingfileattributesofeachenumeratedfile.Thissecondhandleisimportantforefficiency:although9 1 frIhspJjhs btbrb/\ %>*`+,/\038;>@DIAJJb/`."^%]'+-^.d123w589<?DGJJ`./^d^dt^d '^dr^d) ,/2689=)@Ck JJ^d/\7/! *+b03j5 >g@E{JJ\/Z!Z YD YD U {Fl> M (*,U RbtRbxRbRbtRb e eRbxRb )RbtRb*RbrRbDL JlRbtRbObRbOur "<"/>HtH 8{HrH9?BVEzJJHGtGrG h&)&-0!58X=?EGJJGEEcW#&(,,/i1 35;K;KEEtEEJiEErEEJJEECr Dz! *E*ECrtCr 3CrrCr38Cr ? 0 )z+V 38m;\?IBETH"JJ? >. wP#%(,0 3g738>@m@m>.t>.C>.r>.D[IJJ>. <[ V ",%)+m-2B347;D<?cADG G <[t<[Ji<[r<[JJ<[ : zQ!6$D& -2468:4;2?}DYEHJJ: 8a !#'*#./008t84 8r84s89B9B8s8;s>CD(GJJ8 6 6r6 6 3z u F r"0%b*,B.2 ;R?ADJFIJJ3z 1P/bd !W&*x+0516h8=@B JJ1 /|3t / ,ut ,ux,u,ut,u,ux,u!>%,ut,u&,ur,uDL Jl,ut,uOb,u)r )x)!>)r)!$$)x)))r)*++)x)0)r)14d9=AdDGGI6JJ)'po$'c*-_265l8 ?@B=B='x'H'r'I JJ'%x3%r%CC%t%%r%x $' +-/2/2%x%4%r%549% "zt 11"zx"z"zt"z"zr"zDL Jl"zt"zOb"zr\nnt r!""x'r()g,.397;<,<,t EirF-FIJJ,"$(O*+ 288t?r?D %v 9%r%?% } uA, ' /257\;<@2AHJJ} t r"_%(,F.235, =3A[C1IJJ ! E#<%m**t2Cr2 f K]8 '*,/0589F=>DGJJf  &n[?#(+0002-7:?EdFkJJ  )  %k(!(+0446 E9JJ  q?`18onecouldjusttakethefilenamegivenbytheenumeratorandpassittoGETFILEINFO,thedevice,inthecourseofenumeration,usuallyhasitsfingersonthefilecloselyenoughthatitneednotperformtheseconddirectorylookupthataGETFILEINFOoutofthebluewouldrequire.Thecallerofthedirectoryenumerationcodespecifiesaheadoftimewhich,ifany,attributeswillberequired(anecessityformostfileserverimplementations).Informationfordeviceimplementors.AfilegeneratorisanobjectrepresentedasalistdescribedbytherecordFILEGENOBJ,exportedfromFILEIO:(RECORDFILEGENOBJ(NEXTFILEFNFILEINFOFN.GENFILESTATE))NEXTFILEFNandFILEINFOFNarefunctionsofthedevice'schoosingthatwhencalledwillreturnthenextfile,andattributesforthatfile.GENFILESTATEisarbitrarystatemaintainedbythegenerator.Withthatasbackground,herearethepiecesofdirectoryenumeration:(GENERATEFILESDEVICEPATTERNDESIREDPROPSOPTIONS)[Devicemethod]ReturnsageneratorthatenumeratesfilesmatchingPATTERN,whichisastringthathashostanddirectoriessuitablyfilledinfromdefaults,andmaycontainthepatterncharacter``*''tomatchanarbitrarynumberofcharacters.DESIREDPROPSisalistoffileattributesthatmayberequestedduringtheenumeration;theymustbevalidATTRIBUTEargumentstoGETFILEINFO.OPTIONSisalistofoptionstotheenumeration,chosenfromamongthefollowing:SORTThefilesshouldbeenumeratedinsortedorder.Ifthisoptionisnotspecified,thedeviceisfreetoenumeratefilesinanyconvenientorder.Thereissomequestionastowhetherfilesshouldbeenumeratedlowestversionfirst(asIFS'sdo)orhighestversionfirst(asTwenexdoes).Ipreferthelatter,butgivenserversthatdotheformer,wecurrentlymakenorequirementaboutversionorder.RESETLSTInformstheenumeratorthattheenumerationcontextissurroundedbyaRESETLST,sothatitmayperformRESETSAVEstocleanupafteritselfiftheenumerationisaborted.Cleaningupcanbeaverymessybusinesswithoutthisinformationaboutthescopeoftheenumeration,soallcallersof\GENERATEFILESarestronglyencouragedtoprovideit.GENERATEFILESshouldreturnafilegeneratorwithasuitableNEXTFILEFNandFILEINFOFN.Finepointaboutmissingfieldsinthepattern:nullfieldsinPATTERNmatchonlyfilesforwhichthecorrespondingfieldisnull.Anullversionisinterpretedashighest.Thus,DIR*=DIR*.*=DIR*.*;*enumerateseverything.DIR*.=DIR*.;*enumeratesallversionsoffileswithnullextension.DIR*.;enumerateshighestversionoffileswithnullextension.DIR*.*;enumerateshighestversionofeverything.Itisdifficultforsomedevicestoenumerateonlyhighestversionoffiles;thereareseveraldevicesinthesystemthattreatanullversionthesameasversion*.However,everydeviceshouldtryitsbest.Withsomework,anydevicethatcanenumerateallversionscanenumeratejusthighestJ fr hsp Lhs br Q&7!#&$ -s03 4X55btb ?8brb@ B_FHJJb `./  %T'H)+0P5%79$DF`JJ`. ^d^dt^d ^dr^d!8#~% ':*%."33i69;!=RB JJ^d \ f 8p!"% +.068u>Z@DNFJJ\ ZZ WVz MXS 4WVrWV J!!WVuWV#)UWVrWV)*,0 79{:<BDjFJJWV Ukt ZUkrUk UktUk UkrUk!UUkQt ! + 56 BQrQBQ Nwt ZNwrNwccNwtNw NwrNw5 o&N'*2/647;>AEGJJNw L 0 #CLtL 'LrL'z(.M1` 8e:C< BCCFI@JJL J Y# +J G`t G`xG`G`tG`G`xG`!-G`tG`""G`xG` *G`tG`++G`xG`1G`tG`1G`rG`@EJlG`tG`ObG`Dsr &)//DsxDs5 DsrDs59;;7:<AEEFJJ32 d$'@+,/25:7<?SEeHJJ20I %f)-180I-et-er-e#% ,/2W :l?T@ GIJJ-e+t$+r+%X')+$.3j3j+t+:+r+;=A(C1FbIJJ+) I (e)/l058,:<>-AZEJJ)'"% ,o0!2S57{9 ACmE/I7JJ'&+t )&+r&+), 1 8=9>?&+#>t |#>r#> $%'T-A0,1)6 6 #>t#> >s#>r#>>ATAT#>t#> I#>r#>J#> QO" #%O',/3<44 Qx Q:8 Qr Q:>ADFJJ Q "#$w'+, 35T:8:>6>6><t<rk##t r \""t%p)r) 1 7t<rBtV!r" )!*/14F719 ?t<r $)p./2P5;7 =t<r $)p./ 6)AY|"$4*--2y67$8<?|AF*JJ%#ft"Q&)<,.022%t%3%r%4q4:>BG IJJ% Ro}"-&~)[+24:<CF4JJ R q?` 19versionifitenumeratesinsortedorderandusesperhapsalittlelookaheadtoassurethatanynameitreturnsistheoneofhighestversion.(NEXTFILEFNGENFILESTATENAMEONLY)[FileGeneratorComponent]Generatesthenextfile,returningitsnameasastring,orNILifthegeneratorisexhausted.GENFILESTATEisthestatecomponentofthefilegeneratorreturnedfromGENERATEFILES.NAMEONLYmeansthatthecallerisonlyinterestedinthefile'sName.Extfields,notthefullfilename(andnomorethanoneversionofthefileneedbeenumerated);however,itisalwayspermissibletoreturnthefullfilename.TheNAMEONLYoptionisusedbySPELLFILE.(FILEINFOFNGENFILESTATEATTRIBUTE)[FileGeneratorComponent]ReturnsthevalueoftheATTRIBUTEpropertyofthefilemostrecentlygeneratedbytheNEXTFILEFN,i.e.,effectively(GETFILEINFOlatest-nameATTRIBUTE),buthopefullymuchfaster.ATTRIBUTEmusthavebeenamemberoftheDESIREDPROPSargumenttoGENERATEFILES.Notalldeviceimplementorsareenthusedaboutimplementingapatternmatcherforfilenames.Thefollowingfunctionsareprovidedtohelpout:(DIRECTORY.MATCH.SETUPPATTERN)[Function]AcceptsasPATTERNafilenamestringsuchaspassedtoGENERATEFILES.ReturnsanobjectsuitableasafiltertoDIRECTORY.MATCH.(DIRECTORY.MATCHFILTERTESTNAME)[Function]MatchesTESTNAME,afilename,againstFILTER,theobjectreturnedfromDIRECTORY.MATCH.SETUP.ReturnstrueifTESTNAMEmatchesthepattern,falseifnot.Thematchiscase-insensitive.(\NULLFILEGENERATOR)[Function]Returnsafilegeneratorthatproducesnofiles.(\GENERATENOFILESDEVICEPATTERNDESIREDPROPSOPTIONS)[Function]Returnsa``stupid''filegeneratorfordevicesthatdon'tknowhowtoenumerateingeneral.IfPATTERNcontainsnowildcards,butnamesafilethatisINFILEP,thenthegeneratorproducesexactlythatfile.IfPATTERNcontainsawildcardintheversionfield,itusesGETFILENAMEtolaboriouslygeneratealltheversionsofthefile.Inallothercases,\GENERATENOFILESreturnsanullfilegenerator.Informationforclientsofdeviceenumeration.Thefollowingfunctionsmakeupthe``public''interfacetodirectoryenumeration:(\GENERATEFILESPATTERNDESIREDPROPSOPTIONS)[Function]ReturnsafilegeneratorobjectforenumeratingthefilesmatchingPATTERN.PATTERNisexpandedbyaddingthedefaulthostand/ordirectoryifappropriate.SeedescriptionoftheGENERATEFILESmethodfordescriptionofDESIREDPROPSandOPTIONS.J R frIhspJjhsbr.g  9$2'*M-2 3#6(<>BDG0JJb`7<z("@'.'.`7`7'4`7 \t \x\ \t\\x\$^\t\%5\r\9<C Jl\t\Ob\Yr4%'+-.3E5-5-YtY7YrY8[9 55JexJe#@GJJJeHsHxH]HrH"&+-3N588HxH AHrHCHIAJJHFt |FrFF CN  T$( 1318=@BGcHJJCN Ab!$:A >tEE>x>">t>#v>r>DL Jl>t>Ob>;&r``;&x;&;&r;&Am $(l+-M13b3b;&t;& >M;&r;&?+?DFJJ;&9Su9St9S)89Sr9S)9S 5t;;5x5l5t5CC5x5#5t5$t5r5DL Jl5t5Ob52rRR2x22r2"K%+_1D1D2x25u2r27;G@GJJ21"t"41"r1"##(+,,1"x1"3<1"r1"38;Q@\CDGHJJ1"/O#/O +t+r+DL Jl+t+Ob+(r!['(+( %t%x%%t%XX%x%#%t%$$%x% -%t%.W.W%x%3%t%4]%r%DL Jl%t%Ob%"r $%N',q/M269;B]DIIlJJ" x r o $?&*,'.1W22 t 8 r 9~<>EJJ /Ox"1r"()O.037;T<??t HrIAJJ# w &'),r,.0N37o7o#t#D#r#EBIJJ#P9s eP z ! %]r&G&)/59;>* CIAJJ   tddxtx &t'c'cx,t-irDL JltObr"$ ,.17T7Tx<r=`==xCrCqDJJ ,ZX $4)x/1 :4;Y> F8HJJ  t | r  " )+%+% x  4 r 4t66 x <, r < g q?`20(\GENERATENEXTFILEGENERATORNAMEONLY)[Function]Returnsthenextfile,asastring.GENERATORistheobjectreturnedfrom\GENERATEFILES;NAMEONLYindicatescallerdoesnotrequirethatthefullnamebereturned,butthatthenameandextensionaresufficient.(\GENERATEFILEINFOGENERATORATTRIBUTE)[Function]ReturnsthevalueoftheATTRIBUTEpropertyofthefilemostrecentlygeneratedby\GENERATENEXTFILE,i.e.,effectively(GETFILEINFOlatest-nameATTRIBUTE).ATTRIBUTEmusthavebeenamemberoftheDESIREDPROPSargumentto\GENERATEFILES.(DIRECTORY.FILL.PATTERNPATTERNDEFAULTEXTDEFAULTVERS)[Function]ThisfunctionisusedtofillindefaultsinPATTERNbeforepassingitto\GENERATEFILES.IfPATTERNdoesnotincludeanextensionorversion,butthosefieldsarenotexplicitlyomitted(e.g.,``FOO'',butnot``FOO.'';``FOO.BAR'',butnot``FOO.BAR;''),theyarefilledinwithDEFAULTEXTandDEFAULTVERS,whichthemselvesdefaultto``*''.ThisfunctionisusedbytheDIRcommand,andshouldprobablybeusedbyanycodethattakesauser-suppliedpatternandenumeratesfilesfromit.<  fr hsp Lhs btbxb!btb!!bxb(btb)obrbDL JlbtbObb_r,> %%%_x_,_r_-?.15*:>.>._t_ I_r_JJ_]AxM]Ar]A; #&**-y/257=W?B`DH9JJ]A[w} s[w XtXxX!XtX!!XxX(sXtX)JXrXDL JlXtXObXUr`X""UxU)|UrU*0369= BHJJUSOtSOrSO"] ((SOtSO 3SOrSO3 ::SOxSOASOtSOB[SOrSOCBCCSOxSOJiSOrSOJJSOQ|  K!$$Q|xQ| ,Q|rQ|-V3O44Q|tQ| @Q|rQ|@Q| NtNxN#vNtN$M$MNxN +NtN,,NxN 5JNtN6!NrNDL JlNtNObNKr1!#(*s*sKxK/KrK0\49:<-?BBGxxGx JiGxrGxJJGxE++ExE ErE_ M '+-400m3h8:=,? AMAMEtECErED:JJEC3N*"P$7&),01( 9>1@ HJJCBB q?`  TIMESROMAN   HELVETICA TIMESROMAN HELVETICA  TIMESROMAN  TIMESROMAN ~GACHA  TIMESROMAN TIMESROMAN  TIMESROMAN~GACHA j ^ /%3A'O _[ g r ~  N 4 4  EOj/ןg{DSK3}STREAMS.TEDIT;23VANMELLE30-Nov-84 14:17:38