UsingtheInterlisp-DRS232FacilityFile:RS232.ttyCreated:Jan10,1983Revised:Feb21,1983,andAugust18,1983,byJonLWhiteBasicRS232FacililtySupportFunctionsThroughaspecialcircuitboardpluggedintotheparallelportofaDolphin,serialRS232communicationsmaybeinterfacedusingthefollowingbasicfunctions.Ascharactersarriveinattheinterfaceport,theyarestoredinaringbuffer(andtheoutputfunctionswillbuffertheirdatainaringbufferuntilitisfull,oruntilexplicitrequestismadetoforceitout).Sincethereisnomicrocodesupportforbufferingthecharactersastheycomein,therearesomelimitationsusingthisfacility--primarilythattheuserhastocalloneofthefunctionswhichwillupdatetheinputringbufferatintervalsfrequentenoughtoinsuregettingallthecharacters.RS232INIT:beforeusingtheRS232facility,itisnecessarytoinstallcertainparametersintheINS8250chipontheabovementionedboard;thefourargumentstothisfunctioncorrespondtothedesiredBaudrate(150,300,600,...9600aresupported),thenumberofbitsperserialcharacter(i.e.,7or8),whetherornottousethe8thbitasaparitybit(andifso,whetherparityistobeoddoreven),andthenumberof"stop"bits(exceptinunusualcases,1thedefaultvalue,isusedhere).CAUTION:thevalueofRS232INITasaglobalvariableisusedbythesedriverfunctions;donotresetitatanytime.Aglobalvariable,RS232XON\XOFF?,ifnon-NIL,causesthedriverfunctionstolookfor^Sontheincomingside,andto"gag"theoutputtransmitteruntilasubsequent^Qhasbeenreceived;itwillprobablycauseunduetroubletosetthisflagtotrueifthecorrespondinghostdoesn'talsoobeytheXON-XOFFprotocols.Thisvalueis,ofcourse,temporarilyturnedoffbytheFTPprotocols,whichtransmitandreceiverandombytes.RS232CLEARBUFFER:oneargument,typicallyoneof(INOUTPUTBOTH)thecorrespondingringbufferiscleared(andthedatalost);also,returnwillbedelayeduntilanycharactercurrentlybeingsentoutbytheINS8250chiphasbeenfullytransmitted(thisway,notonlyistheringbufferempty,butsoistheone-characterbufferintheINS8250).RS232FORCEOUTPUT:noarguments.Ensuresthatalldataintheoutputringbufferisactuallytransmitted"onthelines".Oneuseofthisfunctionistoensurethatalldataareout--itwon'treturnuntilthisistrue[butalsoseeRS23BACKGROUNDbelow].RS232BACKGROUND:oneargument,"state"The"state"argumentmustbeamong{OFF,INPUT,OUTPUT,BOTH,ON};exceptforinputofOFF,thisturnsonabackgroundlow-levelprocesswhichwillservicetheUARTatleastonceevery16millisecondsand/orflushouttheoutputbuffer.A"state"ofOFFshutsthisbackgroundactivityoff.A"state"ofINPUTcausesonlytheinputbuffertobeserviced;OUTPUTforonlytheoutputbuffer,andeitherONorBOTHforbothbuffers.Aperiodp c/ b6q b6 ` oFyP'Zd *+018J` _ _ ^.%^. \2\ [~y2 #)-12;48=,[~ Z& Z& X X Wv oFyP' )&/7sWv V V T oFd$)&/47m>C/EGbGhT SnyZd )-Y/ 9>%AISn R 1 %+.004DH9JJP Of Of N$&+3:9% GbIIL K^LK^ Jy )&.02c9C/F?F = oFPd !%)& 3:6C/FF= << ;> oF; $*-Y03:69=N@C/DI;> 9 oFZ"n(O*-Y/3:5;>BXH9I9 8 oF'Z!(O.0/3:9?BXFF8 7676 5 oF1; )&+-Y3::=NADH?5 4 oF' d; $)&+.0154 3. oFP1!/19>BXGh3. 1 oF1d #E%)&059;@DI1 0~ oF Zd (O*.02c:;>%BXI0~ /& oFPZ!$)&-Y/469 EI/& - oF1d (O 12c6;>AGh- ,v oF Z;!$'x* 49@DJJ,v + oF'7+ ) ) (n (O0469?D (n ' oF d!'x)048D%ADGbGb$f ## ! oFy )&.02c59%AF V oFyZ"n ,/3:9:>%ADGhV  oFZ $(O,/3:58D=NC/Gh  oFy1d!$ 17s N N  ;&,  oFZ$&+06=NBXFGbGb FF  oF1d!&)&* 4 oFZ$(O-Y/ :@EII> FL oF'd$&)/3: BXBXb6 ` '` _ oF  $+3:6 @DII_ ^. o u^. \ oF'$'x+\ [~ [~ Z& 1 $%,/4BXFFWv VV T oF''x)+/3:5;? H?T Sn oF!)&-Y047m:?DISn R R P 1$ -Y.02c48D=NBXIP Of oFPd#E%(O*03:9:=N?H9IOf N oF ;$(O+.016>%@BXGbGbN L#L K^ oF1;"n&*/5>%FFK^ JJ H oFZ #E& /2c5:BXDGhH GV oFP#E%).06>%C/FGV E oFy'x(O+19 BXDE D oF'Zd#E$*-Y 9 oFP#E ,.02c46 9 oF'Z $,.02i9 8 8 76 1& /02c9%A I5 4 oF';%(O)0149=NDD4 3.3. 1 oF "n$(O+3:;>% JJ1 0~ oFyZ#E&)&,049>%ADD0~ /&/& - oFZ (O*3:59%DD- ,v,v + oF'Z!$)-Y 6 @C/F+ ) oFy;%&*/2c JJ ^  oFy;"n'x,049=NBXEH9H9 # V oF #E&+14 =NBXDGbGbV #  oFy)*/46=N@BXJJ N o uN  oFy#E(O*.05 ?DII  o u F oF !$'x/15 o u>  oF; #E*.0/ 9BXEFF  6 oFy1d#E)&/3:9 DDE 6 oF' "n*/).However,inmostcases,thisstreamapproachwillnotworkunlessthe c8 b6q oFP$&/1AAb6 ` ` _ oF d(O*/13:9DGbJJX Wv oF'Z"n&)&/2c48D>%DFIWv V oFP' #E ,03:9BXH9H?V T oFZ"n)/14;?BXEET SnSn R oFd$(O*/3:@DDR PP Of oF d!$*-Y0 %EJJ= < oFy!&)&+047m>%@DH9H?< ;> oF !$*147m=N>%@@;> 9 9 8 oF'!$'x*/19>C/FF8 7676 5 oFP$%)&/2c =N@GbGb5 44 3. oF1;$*+,3:9>%DGbJJ3. 1 oF1 0~ 0~ /& !$-Y 9=N>%>%/& -- ,v oF1;#E)/7m9=NBXDH9H9,v +FL+ ) oF  +/2c47m:>%C/EE) (n oF"n&'x.017mBXFF  N N  ;%  oFP ),149 oF$">   6 6 oFZ; 'x) 3:69?AGbGh P1;"n$+ 4%DDZ& XX Wv oPZ"n%.0158DAGhWv VyZ )&-Y4:=N@DFV T(O-_T Sn Sn R oF1d#E&+0 9AAR P -P Ofd (O+2c9;C/EEOf NN L  "n'x*/7m:BXFIIL K^ uK^ JZ%(O/2c6:?C/H9JJJ H $(O-Y/2c67m @C/H9JJH GVFP &(O03:5=N@H9H9GV E#E DPZ(O*,3: %BXDH9JJ?F =P1'x,/2c8D: ;> 9 9 8 8 76 76 5 oFyP'Z1$$+5 4 4 3. oF1 "n&*2c ;DEI3. 1 #E&+0149ADJJ1 0~!$, 5=N?BXEII0~ /&P;-Y2c49>% II/& -FL- ,vFyZd#E&*2c8D@C/C/,v +PV+ ) o;&)2c5 >DII) (nyZ $&)&-Y/3:9;>FF(n ' Z $)&-Y49>DFJJ' % "n$+-Y49=NEH9H9% $fFL$f # #E'x*2c8D=NEH9H9# !FL! ^Z!(O*.05 >ADFF ^  d $*-Y05>%ADII V!'x)-Y05=NC/IV  o'#E*3:44  oFP )& 2c59>%AII N o uN  "n% /469;>C/EII  Z "n$(O,02c7m: DGbGb F#F PZ(O,/47m9=NBXDII  o u >Fy "n&*3:4 =N@DJJ> yZ#E'x+158D:>DEH9H9 # 6'1 "n%(O+04:=N@DGbI 6 ;"n%4 >%BXDD  . o;$'x 49=NAGbGb. # q?[output.Caveat:OutputtothetheDolphindisplaytakesanon-trivialamountoftime(e.g.,justgoingthroughthecharacterprintoutroutines,and"painting"acharacterontothescreenbit-maprequiresoveramillisecond;scrollingamodest-sizedwindowmaytakewellover30milliseconds).Withoutadditionalmicrocodesupport,tomaintaintheinputringbufferasynchronously,itisquestionablewhetherratesabove2400baudwillbeacceptableforRS232CHAT,andtheremaybeocasionalproblemsabove1200baud).At"slower"speeds,thatis,atlessthanabout600baud,theuseofRS232BACKGROUNDmayalleviatetheseproblems.However,RS232CHATwillpayattentiontotheDSPSCROLLsettingofthechatwindow,andwilldo"roll"moderatherthan"wrap"modeprovidedthatitcandosowithoutdroppingcharacters["roll"describesthe"scrollup"actionwhentypeoutreachesthebottomofthewindow].IftheXON/XOFFprotocolisbeingused,orifthebackgroundprocessmentionedaboveisinoperation,thenlikelytherewillbenoproblemisusing"roll"mode.Escapefrom"duplex"modeismadebytypingthethecharacterwhichisfoundinthevalueof\RS232ESCAPE.CHARCODE,currentlyinitializedto(CHARACTER#B)[thishappenstobemiddle-blank].Typing"?"justaftertheescapecharacterwillgiveasmall"helpmessage;thecommandstobeusedinthismodeareallone-letter:B-sendaBREAK(0.25seconds)E-changetheescapecharacterF-deactivatetheXON\XOFFprotocolH-callthefunction(HELP),withinterruptsre-activatedL-callthefunction(RS232.PROMPT&LOGIN)O-settheXON\XOFFprotocolactiveQ-forquitandexit,presumablybacktoLISPXS-setthespeedoftheRS232port;?willdisplaychoices.-'Return'keysendstoremotehost-'Return'keysendstoremotehost^B-runa"break"orHELPloopR-callRAID7-truncateincomingcharactersto7bits(thisisnecessarywhenyouhaveopenedan8-bitconnectionignoringtheparitybit;youreallyonlywanttoseethelower7bitsinterpretedasacharactertobeprintedonthewindow).8-undothe"7-bit"modeabove(justincaseyouactuallywantedtoseetheeightbit--typicallytheprintoutwillbejustthesameasasthe7-bitprintout,butpreceededbya"#"whentheeighthbitisoninacharacter.)Additionalcontrolmaybeexercisedwiththepop-upmenuobtainedbypressingthemiddlemousebuttonwiththecursorintheRS232CHATwindowwhileRS232CHATisactive;itscommandsareessentiallyself-documenting,andareasuper-setoftheabove-mentionedcommandsavailablefromthekeyboard.Inparticular,it'spossibletoalterwhatRS232CHATthinksisthe"NewLine"character;Interlisp-D'sdefaultistochooseCR,butforconnectionstosomesystems,LFisamuchbetterchoice.Twoothercommandspermit"toggling"(thatis,switchingthestatefromonechoicetoanalternate,andvice-versa):~LocalEchoand~RollMode.ThelatterwillchangetheDSPSCROLLof\RS232CHATWINDOW;theformerwill"toggle"theuseofthelocalechostreamprovidedinthecalltoRS232CHAT(orwilluse\RS232CHATWINDOWifnostreamwasprovided). c8 b6qb6 ` ` _ oFd $*168D BXH9JJ_ ^.1;$(O08D@DD^. \ '-\ [~ 1"n)&)157m BXI[~ Z& d $)&-Y/ BXBXV T '-T SnFP1!)&.02c8D9;C/ISn Ry1d"n%*.014ADDR PP OfZ1 )&-Y09;>GbGbOf NN L o#E%+/59?DDL K^yK^ J (O 18D@DJJJ H uH GV"n%+.0199C/Gh?F =F' $&+08D;C/EH9H9= <#< ;> o1 %;> 9 o!(U9 8 o'~8 76 o d$+76 5 oZ&* 4 >+5 4 oZ04 3. o'&+3. 1 o'Z ).0041 0~ o'"n'x,.02c9?0~ /& oP;#E'x)/3@/& - oP;#E*-Y3:6- ,v od$'~,v + o7+ ) oZ )&+-Y169AEH?) (n oF;#E ,47m=NADI(n ' oF#E(O).0 8D:%EGhV y &*.0469BXGh Z!$,/ 9H? NFP;!/6>C/EN P' $,/48D@FH? F  +2c47m=N@DF F #E%(O).04:;;F  oF;$ -Y2c5>%AFJJ  u >P "n -Y 69 C/DGbGb>  Z #E2c5;?GbJJ 6 u 6  o'x)-Y14".Thefollowingtwofunctionsaremostusefulwhentryingto"chat"toahostthroughanRS232connectionrunningataspeedhigherthanInterlisp-Dcansupportfordisplaystreamactivities:RS232LOGIN:6arguments,mostoptional.FirstisthenameofahostmachinewithwhichtheRS232portiscorresponding,secondisthedesiredusername/login.idonthatmachine,thirdisthepasswordneededthere,andfourthisthe"hostsystemtype";theremainingtwoargumentsareconcernedwheretoechotheactivitycausedbythisfunction,andaremainlyofinteresttoothersystem-levelfunctions.Ifeither"username"or"password"isNIL,thewillbeobtainedviaPROMPTFORWORDfromthekeyboard(thisissothatyoudon'thavetohavepasswordsincodefiles);thereisalsoaninternalcacheoftheinformationabouthost/username/password,justasiskeptforloginsovertheEthernet.[seedocumentationofPROMPTFORWORD]WhentheHost'ssystemtypeisknown,thenadatabaseofloginprotocolsisconsultedtofigureouthowtosend(automaticallyandblindly)thenecessarycharacterstoeffectalogin.Atconvenientmoments,theoutputfromthehost,whichisaccumulatedintheRS232linebuffer,willbeoutputfortheuser'sperusal(thefifthargumentisastreamforthisprintout:NILdefaultstotheprimaryoutput,NONEgagsthistype-out;window,filesets.allareacceptablehere).Aprimaryreasonforthisfunction'sexistence,besidesthecacheingofsuchinformationaslogin.idandpassword,istopermitloggininatspeedswhichcannotsupportRS232CHAT(seedocumentationbelow).RS232.PROMPT&LOGIN:oneargument.Promptstheuser(viaPROMPTFORWORD)totypeinthenecessaryinformation,inthePROMPTWINDOW,tocallanduseRS232LOGIN;theargumentishandedtoRS232LOGINasitsfifthargument c8 b6qF!$(O+ 6>%EEb6 `` _ o "n%47m: E_ ^. ^. \ oFZ 'x.0E\ [~ o(O.03:6[~ Z& Z& X #E%'x+.03:7m9AC5X Wv oF #E%*-Y2c4DIIWv V#V T oFy )&159BXIIN L uL K^ oF1 #E&/7m;?GbJJK^ J uJ H oFZ! *-Y/3:9H GV "n)-Y/3:8D%BXDD@ ?F V?F = oFy; 'x(O,2c4 >%@BXFF= <yP< ;> oF'Z$*/047m ?;> 9  #E(O+3: =NC/FF9 88 76 oF"n(O-Y049?DGbGb76 55 4 oFZ#E)&-Y3:6>%EGh4 3. oF #E ,03: =N@DD 3. 1 oFZ; (O,// 8J1 0~ 0~ /& oFd%)&-Y3:7m=N?EH9I/& -Zd &-Y/16%@BXE) (n oF1;!&*-Y 9?BXD(n ' oF$&*2c3:8D:>%D' % oF'd#E%)&.049=NEH?% $f oF"n#E(O*/2c9?BXE$f # oFd#E%-Y/4 ? H?# ! oF "n +.02c59AD   oF Zd158D:>BXGh V oFy;#E /1 =TV  oF1$)&+157m>AE  oF1!$)-Y03:7m DGbGh N oF1! *-Y3:4:;>% FN  oF1#E&+03: =N?C/H9H?  oFy1d%)&,2c9=NBXI F oFyZ(O+3:59?EF  oFy#E$*/47m: DI  oF$ -Y 6=N@H9I > oFy &)2c47m=NC/EGh>  oF'1%.02c >%D  6 d )&)048DMUMBLE")(RS232PUTFILE'{DSK}RUN.DCOM'BINARY'MODEM"MODEMRBRUN.DCOM")BothendsoftheMODEMprotocolhave"synchronizing"features,soatypicalscenarioofusagewouldbetouseRS232CHATtologintothehost,andthensimplyputtheMODEMprograminitswaitstate,bytypingwhateverargumentsitneeds,andfinallyexitingfromRS232CHATandcallingRS232GETFILE(orRS232PUTFILE)directly,withoutthefourthargument.Thefourth-argumentfacilityisprovidedsothatonemayuseRS232FTPatspeedsgreaterthanwouldbeavailableforRS232CHAT;logincouldthusbeachievedthroughuseofthefunctionRS232.PROMPT&LOGIN.TheglobalvariableRS232FTPTRACEFLG,ifnon-null,causesatraceofactivitytobeprintedoutonthefile/streamspecifiedbytheglobalvariableRS232TRACEFILE;itthevalueisPEEK,thenonlya"+"willbeprintedforsuccessfultransitofpackets,and"-"forunsuccessfulones;anyothernon-nullvaluecausesamoreverboseoutput. c8 b6q oFy! *b6 ` ` _ _ ^. ^. \ oFyP'Z1 %,\ [~ [~ Z& oF"n ,/04;>DH9H?Z& XP )&,3:9@IISn R$&)&.006 C/H9H9R P#P OfF $),17m @DDOf NyN Ly1!'x*-Y47m;=NAGbIL K^ 1#E%*-Y069>%DH?K^ J#E% /2c8D99>%?DH9H9J HH GV o1;#E(O045;>%DIGV E "n%,03:6;@FE D !%) 4 @DDD CNCN A oy1$ .02c48D: DIIA @L@ ?F '?F = = < Zd$ .014=N>%C/I< ;> oF'Z #E(O+/4 >DH9H?;> 9 oF  $&,03:9> II9 8 oFZ; 'x*/3:69 DJJ8 76 oFPd (O-Y1 ;?DGbGh76 5 oF d#E+/47m; EJJ5 4 oF Z!$'x-Y/ 9%B^ F o1 "n'x,03::@F F'+   > oF.009>@D>  o $&) 4BXGh y #E&+.03:7m;=N@D 6 o' 'x)148D; FF 6 # FP%'x+2c8J . . q?[SeveralimplementationsoftheMODEMprotocolforothermachinesareavailable:onefortheIBM/PCisavailableonfloppydiskthroughXSIS(andisalsoon[MAXC]IBMFTP.ASC).Severalfilesareavailablealsoon[MAXC]forVAX/VMSusers:XMODEM.FORandQIO.DCKareanimplementationinFORTRAN;TOXMOD.FORandFMXMOD.FORarehelpfulfordealingwiththestructureoffilesinVMS'srecordmanagementsystem. c8 b6q b6 `!$)149ADD` _ V_ ^.Fd%(O.02c9=NADH9JJ^. \ 'x,/8D II\ [~FL[~ Z& $*.00 =N?GbGhZ& X ' $*.049LIBRARY>RS232.TTY;3JONL.PA12-Mar-84 16:37:50