ckermit70.txt 711 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776777778779780781782783784785786787788789790791792793794795796797798799800801802803804805806807808809810811812813814815816817818819820821822823824825826827828829830831832833834835836837838839840841842843844845846847848849850851852853854855856857858859860861862863864865866867868869870871872873874875876877878879880881882883884885886887888889890891892893894895896897898899900901902903904905906907908909910911912913914915916917918919920921922923924925926927928929930931932933934935936937938939940941942943944945946947948949950951952953954955956957958959960961962963964965966967968969970971972973974975976977978979980981982983984985986987988989990991992993994995996997998999100010011002100310041005100610071008100910101011101210131014101510161017101810191020102110221023102410251026102710281029103010311032103310341035103610371038103910401041104210431044104510461047104810491050105110521053105410551056105710581059106010611062106310641065106610671068106910701071107210731074107510761077107810791080108110821083108410851086108710881089109010911092109310941095109610971098109911001101110211031104110511061107110811091110111111121113111411151116111711181119112011211122112311241125112611271128112911301131113211331134113511361137113811391140114111421143114411451146114711481149115011511152115311541155115611571158115911601161116211631164116511661167116811691170117111721173117411751176117711781179118011811182118311841185118611871188118911901191119211931194119511961197119811991200120112021203120412051206120712081209121012111212121312141215121612171218121912201221122212231224122512261227122812291230123112321233123412351236123712381239124012411242124312441245124612471248124912501251125212531254125512561257125812591260126112621263126412651266126712681269127012711272127312741275127612771278127912801281128212831284128512861287128812891290129112921293129412951296129712981299130013011302130313041305130613071308130913101311131213131314131513161317131813191320132113221323132413251326132713281329133013311332133313341335133613371338133913401341134213431344134513461347134813491350135113521353135413551356135713581359136013611362136313641365136613671368136913701371137213731374137513761377137813791380138113821383138413851386138713881389139013911392139313941395139613971398139914001401140214031404140514061407140814091410141114121413141414151416141714181419142014211422142314241425142614271428142914301431143214331434143514361437143814391440144114421443144414451446144714481449145014511452145314541455145614571458145914601461146214631464146514661467146814691470147114721473147414751476147714781479148014811482148314841485148614871488148914901491149214931494149514961497149814991500150115021503150415051506150715081509151015111512151315141515151615171518151915201521152215231524152515261527152815291530153115321533153415351536153715381539154015411542154315441545154615471548154915501551155215531554155515561557155815591560156115621563156415651566156715681569157015711572157315741575157615771578157915801581158215831584158515861587158815891590159115921593159415951596159715981599160016011602160316041605160616071608160916101611161216131614161516161617161816191620162116221623162416251626162716281629163016311632163316341635163616371638163916401641164216431644164516461647164816491650165116521653165416551656165716581659166016611662166316641665166616671668166916701671167216731674167516761677167816791680168116821683168416851686168716881689169016911692169316941695169616971698169917001701170217031704170517061707170817091710171117121713171417151716171717181719172017211722172317241725172617271728172917301731173217331734173517361737173817391740174117421743174417451746174717481749175017511752175317541755175617571758175917601761176217631764176517661767176817691770177117721773177417751776177717781779178017811782178317841785178617871788178917901791179217931794179517961797179817991800180118021803180418051806180718081809181018111812181318141815181618171818181918201821182218231824182518261827182818291830183118321833183418351836183718381839184018411842184318441845184618471848184918501851185218531854185518561857185818591860186118621863186418651866186718681869187018711872187318741875187618771878187918801881188218831884188518861887188818891890189118921893189418951896189718981899190019011902190319041905190619071908190919101911191219131914191519161917191819191920192119221923192419251926192719281929193019311932193319341935193619371938193919401941194219431944194519461947194819491950195119521953195419551956195719581959196019611962196319641965196619671968196919701971197219731974197519761977197819791980198119821983198419851986198719881989199019911992199319941995199619971998199920002001200220032004200520062007200820092010201120122013201420152016201720182019202020212022202320242025202620272028202920302031203220332034203520362037203820392040204120422043204420452046204720482049205020512052205320542055205620572058205920602061206220632064206520662067206820692070207120722073207420752076207720782079208020812082208320842085208620872088208920902091209220932094209520962097209820992100210121022103210421052106210721082109211021112112211321142115211621172118211921202121212221232124212521262127212821292130213121322133213421352136213721382139214021412142214321442145214621472148214921502151215221532154215521562157215821592160216121622163216421652166216721682169217021712172217321742175217621772178217921802181218221832184218521862187218821892190219121922193219421952196219721982199220022012202220322042205220622072208220922102211221222132214221522162217221822192220222122222223222422252226222722282229223022312232223322342235223622372238223922402241224222432244224522462247224822492250225122522253225422552256225722582259226022612262226322642265226622672268226922702271227222732274227522762277227822792280228122822283228422852286228722882289229022912292229322942295229622972298229923002301230223032304230523062307230823092310231123122313231423152316231723182319232023212322232323242325232623272328232923302331233223332334233523362337233823392340234123422343234423452346234723482349235023512352235323542355235623572358235923602361236223632364236523662367236823692370237123722373237423752376237723782379238023812382238323842385238623872388238923902391239223932394239523962397239823992400240124022403240424052406240724082409241024112412241324142415241624172418241924202421242224232424242524262427242824292430243124322433243424352436243724382439244024412442244324442445244624472448244924502451245224532454245524562457245824592460246124622463246424652466246724682469247024712472247324742475247624772478247924802481248224832484248524862487248824892490249124922493249424952496249724982499250025012502250325042505250625072508250925102511251225132514251525162517251825192520252125222523252425252526252725282529253025312532253325342535253625372538253925402541254225432544254525462547254825492550255125522553255425552556255725582559256025612562256325642565256625672568256925702571257225732574257525762577257825792580258125822583258425852586258725882589259025912592259325942595259625972598259926002601260226032604260526062607260826092610261126122613261426152616261726182619262026212622262326242625262626272628262926302631263226332634263526362637263826392640264126422643264426452646264726482649265026512652265326542655265626572658265926602661266226632664266526662667266826692670267126722673267426752676267726782679268026812682268326842685268626872688268926902691269226932694269526962697269826992700270127022703270427052706270727082709271027112712271327142715271627172718271927202721272227232724272527262727272827292730273127322733273427352736273727382739274027412742274327442745274627472748274927502751275227532754275527562757275827592760276127622763276427652766276727682769277027712772277327742775277627772778277927802781278227832784278527862787278827892790279127922793279427952796279727982799280028012802280328042805280628072808280928102811281228132814281528162817281828192820282128222823282428252826282728282829283028312832283328342835283628372838283928402841284228432844284528462847284828492850285128522853285428552856285728582859286028612862286328642865286628672868286928702871287228732874287528762877287828792880288128822883288428852886288728882889289028912892289328942895289628972898289929002901290229032904290529062907290829092910291129122913291429152916291729182919292029212922292329242925292629272928292929302931293229332934293529362937293829392940294129422943294429452946294729482949295029512952295329542955295629572958295929602961296229632964296529662967296829692970297129722973297429752976297729782979298029812982298329842985298629872988298929902991299229932994299529962997299829993000300130023003300430053006300730083009301030113012301330143015301630173018301930203021302230233024302530263027302830293030303130323033303430353036303730383039304030413042304330443045304630473048304930503051305230533054305530563057305830593060306130623063306430653066306730683069307030713072307330743075307630773078307930803081308230833084308530863087308830893090309130923093309430953096309730983099310031013102310331043105310631073108310931103111311231133114311531163117311831193120312131223123312431253126312731283129313031313132313331343135313631373138313931403141314231433144314531463147314831493150315131523153315431553156315731583159316031613162316331643165316631673168316931703171317231733174317531763177317831793180318131823183318431853186318731883189319031913192319331943195319631973198319932003201320232033204320532063207320832093210321132123213321432153216321732183219322032213222322332243225322632273228322932303231323232333234323532363237323832393240324132423243324432453246324732483249325032513252325332543255325632573258325932603261326232633264326532663267326832693270327132723273327432753276327732783279328032813282328332843285328632873288328932903291329232933294329532963297329832993300330133023303330433053306330733083309331033113312331333143315331633173318331933203321332233233324332533263327332833293330333133323333333433353336333733383339334033413342334333443345334633473348334933503351335233533354335533563357335833593360336133623363336433653366336733683369337033713372337333743375337633773378337933803381338233833384338533863387338833893390339133923393339433953396339733983399340034013402340334043405340634073408340934103411341234133414341534163417341834193420342134223423342434253426342734283429343034313432343334343435343634373438343934403441344234433444344534463447344834493450345134523453345434553456345734583459346034613462346334643465346634673468346934703471347234733474347534763477347834793480348134823483348434853486348734883489349034913492349334943495349634973498349935003501350235033504350535063507350835093510351135123513351435153516351735183519352035213522352335243525352635273528352935303531353235333534353535363537353835393540354135423543354435453546354735483549355035513552355335543555355635573558355935603561356235633564356535663567356835693570357135723573357435753576357735783579358035813582358335843585358635873588358935903591359235933594359535963597359835993600360136023603360436053606360736083609361036113612361336143615361636173618361936203621362236233624362536263627362836293630363136323633363436353636363736383639364036413642364336443645364636473648364936503651365236533654365536563657365836593660366136623663366436653666366736683669367036713672367336743675367636773678367936803681368236833684368536863687368836893690369136923693369436953696369736983699370037013702370337043705370637073708370937103711371237133714371537163717371837193720372137223723372437253726372737283729373037313732373337343735373637373738373937403741374237433744374537463747374837493750375137523753375437553756375737583759376037613762376337643765376637673768376937703771377237733774377537763777377837793780378137823783378437853786378737883789379037913792379337943795379637973798379938003801380238033804380538063807380838093810381138123813381438153816381738183819382038213822382338243825382638273828382938303831383238333834383538363837383838393840384138423843384438453846384738483849385038513852385338543855385638573858385938603861386238633864386538663867386838693870387138723873387438753876387738783879388038813882388338843885388638873888388938903891389238933894389538963897389838993900390139023903390439053906390739083909391039113912391339143915391639173918391939203921392239233924392539263927392839293930393139323933393439353936393739383939394039413942394339443945394639473948394939503951395239533954395539563957395839593960396139623963396439653966396739683969397039713972397339743975397639773978397939803981398239833984398539863987398839893990399139923993399439953996399739983999400040014002400340044005400640074008400940104011401240134014401540164017401840194020402140224023402440254026402740284029403040314032403340344035403640374038403940404041404240434044404540464047404840494050405140524053405440554056405740584059406040614062406340644065406640674068406940704071407240734074407540764077407840794080408140824083408440854086408740884089409040914092409340944095409640974098409941004101410241034104410541064107410841094110411141124113411441154116411741184119412041214122412341244125412641274128412941304131413241334134413541364137413841394140414141424143414441454146414741484149415041514152415341544155415641574158415941604161416241634164416541664167416841694170417141724173417441754176417741784179418041814182418341844185418641874188418941904191419241934194419541964197419841994200420142024203420442054206420742084209421042114212421342144215421642174218421942204221422242234224422542264227422842294230423142324233423442354236423742384239424042414242424342444245424642474248424942504251425242534254425542564257425842594260426142624263426442654266426742684269427042714272427342744275427642774278427942804281428242834284428542864287428842894290429142924293429442954296429742984299430043014302430343044305430643074308430943104311431243134314431543164317431843194320432143224323432443254326432743284329433043314332433343344335433643374338433943404341434243434344434543464347434843494350435143524353435443554356435743584359436043614362436343644365436643674368436943704371437243734374437543764377437843794380438143824383438443854386438743884389439043914392439343944395439643974398439944004401440244034404440544064407440844094410441144124413441444154416441744184419442044214422442344244425442644274428442944304431443244334434443544364437443844394440444144424443444444454446444744484449445044514452445344544455445644574458445944604461446244634464446544664467446844694470447144724473447444754476447744784479448044814482448344844485448644874488448944904491449244934494449544964497449844994500450145024503450445054506450745084509451045114512451345144515451645174518451945204521452245234524452545264527452845294530453145324533453445354536453745384539454045414542454345444545454645474548454945504551455245534554455545564557455845594560456145624563456445654566456745684569457045714572457345744575457645774578457945804581458245834584458545864587458845894590459145924593459445954596459745984599460046014602460346044605460646074608460946104611461246134614461546164617461846194620462146224623462446254626462746284629463046314632463346344635463646374638463946404641464246434644464546464647464846494650465146524653465446554656465746584659466046614662466346644665466646674668466946704671467246734674467546764677467846794680468146824683468446854686468746884689469046914692469346944695469646974698469947004701470247034704470547064707470847094710471147124713471447154716471747184719472047214722472347244725472647274728472947304731473247334734473547364737473847394740474147424743474447454746474747484749475047514752475347544755475647574758475947604761476247634764476547664767476847694770477147724773477447754776477747784779478047814782478347844785478647874788478947904791479247934794479547964797479847994800480148024803480448054806480748084809481048114812481348144815481648174818481948204821482248234824482548264827482848294830483148324833483448354836483748384839484048414842484348444845484648474848484948504851485248534854485548564857485848594860486148624863486448654866486748684869487048714872487348744875487648774878487948804881488248834884488548864887488848894890489148924893489448954896489748984899490049014902490349044905490649074908490949104911491249134914491549164917491849194920492149224923492449254926492749284929493049314932493349344935493649374938493949404941494249434944494549464947494849494950495149524953495449554956495749584959496049614962496349644965496649674968496949704971497249734974497549764977497849794980498149824983498449854986498749884989499049914992499349944995499649974998499950005001500250035004500550065007500850095010501150125013501450155016501750185019502050215022502350245025502650275028502950305031503250335034503550365037503850395040504150425043504450455046504750485049505050515052505350545055505650575058505950605061506250635064506550665067506850695070507150725073507450755076507750785079508050815082508350845085508650875088508950905091509250935094509550965097509850995100510151025103510451055106510751085109511051115112511351145115511651175118511951205121512251235124512551265127512851295130513151325133513451355136513751385139514051415142514351445145514651475148514951505151515251535154515551565157515851595160516151625163516451655166516751685169517051715172517351745175517651775178517951805181518251835184518551865187518851895190519151925193519451955196519751985199520052015202520352045205520652075208520952105211521252135214521552165217521852195220522152225223522452255226522752285229523052315232523352345235523652375238523952405241524252435244524552465247524852495250525152525253525452555256525752585259526052615262526352645265526652675268526952705271527252735274527552765277527852795280528152825283528452855286528752885289529052915292529352945295529652975298529953005301530253035304530553065307530853095310531153125313531453155316531753185319532053215322532353245325532653275328532953305331533253335334533553365337533853395340534153425343534453455346534753485349535053515352535353545355535653575358535953605361536253635364536553665367536853695370537153725373537453755376537753785379538053815382538353845385538653875388538953905391539253935394539553965397539853995400540154025403540454055406540754085409541054115412541354145415541654175418541954205421542254235424542554265427542854295430543154325433543454355436543754385439544054415442544354445445544654475448544954505451545254535454545554565457545854595460546154625463546454655466546754685469547054715472547354745475547654775478547954805481548254835484548554865487548854895490549154925493549454955496549754985499550055015502550355045505550655075508550955105511551255135514551555165517551855195520552155225523552455255526552755285529553055315532553355345535553655375538553955405541554255435544554555465547554855495550555155525553555455555556555755585559556055615562556355645565556655675568556955705571557255735574557555765577557855795580558155825583558455855586558755885589559055915592559355945595559655975598559956005601560256035604560556065607560856095610561156125613561456155616561756185619562056215622562356245625562656275628562956305631563256335634563556365637563856395640564156425643564456455646564756485649565056515652565356545655565656575658565956605661566256635664566556665667566856695670567156725673567456755676567756785679568056815682568356845685568656875688568956905691569256935694569556965697569856995700570157025703570457055706570757085709571057115712571357145715571657175718571957205721572257235724572557265727572857295730573157325733573457355736573757385739574057415742574357445745574657475748574957505751575257535754575557565757575857595760576157625763576457655766576757685769577057715772577357745775577657775778577957805781578257835784578557865787578857895790579157925793579457955796579757985799580058015802580358045805580658075808580958105811581258135814581558165817581858195820582158225823582458255826582758285829583058315832583358345835583658375838583958405841584258435844584558465847584858495850585158525853585458555856585758585859586058615862586358645865586658675868586958705871587258735874587558765877587858795880588158825883588458855886588758885889589058915892589358945895589658975898589959005901590259035904590559065907590859095910591159125913591459155916591759185919592059215922592359245925592659275928592959305931593259335934593559365937593859395940594159425943594459455946594759485949595059515952595359545955595659575958595959605961596259635964596559665967596859695970597159725973597459755976597759785979598059815982598359845985598659875988598959905991599259935994599559965997599859996000600160026003600460056006600760086009601060116012601360146015601660176018601960206021602260236024602560266027602860296030603160326033603460356036603760386039604060416042604360446045604660476048604960506051605260536054605560566057605860596060606160626063606460656066606760686069607060716072607360746075607660776078607960806081608260836084608560866087608860896090609160926093609460956096609760986099610061016102610361046105610661076108610961106111611261136114611561166117611861196120612161226123612461256126612761286129613061316132613361346135613661376138613961406141614261436144614561466147614861496150615161526153615461556156615761586159616061616162616361646165616661676168616961706171617261736174617561766177617861796180618161826183618461856186618761886189619061916192619361946195619661976198619962006201620262036204620562066207620862096210621162126213621462156216621762186219622062216222622362246225622662276228622962306231623262336234623562366237623862396240624162426243624462456246624762486249625062516252625362546255625662576258625962606261626262636264626562666267626862696270627162726273627462756276627762786279628062816282628362846285628662876288628962906291629262936294629562966297629862996300630163026303630463056306630763086309631063116312631363146315631663176318631963206321632263236324632563266327632863296330633163326333633463356336633763386339634063416342634363446345634663476348634963506351635263536354635563566357635863596360636163626363636463656366636763686369637063716372637363746375637663776378637963806381638263836384638563866387638863896390639163926393639463956396639763986399640064016402640364046405640664076408640964106411641264136414641564166417641864196420642164226423642464256426642764286429643064316432643364346435643664376438643964406441644264436444644564466447644864496450645164526453645464556456645764586459646064616462646364646465646664676468646964706471647264736474647564766477647864796480648164826483648464856486648764886489649064916492649364946495649664976498649965006501650265036504650565066507650865096510651165126513651465156516651765186519652065216522652365246525652665276528652965306531653265336534653565366537653865396540654165426543654465456546654765486549655065516552655365546555655665576558655965606561656265636564656565666567656865696570657165726573657465756576657765786579658065816582658365846585658665876588658965906591659265936594659565966597659865996600660166026603660466056606660766086609661066116612661366146615661666176618661966206621662266236624662566266627662866296630663166326633663466356636663766386639664066416642664366446645664666476648664966506651665266536654665566566657665866596660666166626663666466656666666766686669667066716672667366746675667666776678667966806681668266836684668566866687668866896690669166926693669466956696669766986699670067016702670367046705670667076708670967106711671267136714671567166717671867196720672167226723672467256726672767286729673067316732673367346735673667376738673967406741674267436744674567466747674867496750675167526753675467556756675767586759676067616762676367646765676667676768676967706771677267736774677567766777677867796780678167826783678467856786678767886789679067916792679367946795679667976798679968006801680268036804680568066807680868096810681168126813681468156816681768186819682068216822682368246825682668276828682968306831683268336834683568366837683868396840684168426843684468456846684768486849685068516852685368546855685668576858685968606861686268636864686568666867686868696870687168726873687468756876687768786879688068816882688368846885688668876888688968906891689268936894689568966897689868996900690169026903690469056906690769086909691069116912691369146915691669176918691969206921692269236924692569266927692869296930693169326933693469356936693769386939694069416942694369446945694669476948694969506951695269536954695569566957695869596960696169626963696469656966696769686969697069716972697369746975697669776978697969806981698269836984698569866987698869896990699169926993699469956996699769986999700070017002700370047005700670077008700970107011701270137014701570167017701870197020702170227023702470257026702770287029703070317032703370347035703670377038703970407041704270437044704570467047704870497050705170527053705470557056705770587059706070617062706370647065706670677068706970707071707270737074707570767077707870797080708170827083708470857086708770887089709070917092709370947095709670977098709971007101710271037104710571067107710871097110711171127113711471157116711771187119712071217122712371247125712671277128712971307131713271337134713571367137713871397140714171427143714471457146714771487149715071517152715371547155715671577158715971607161716271637164716571667167716871697170717171727173717471757176717771787179718071817182718371847185718671877188718971907191719271937194719571967197719871997200720172027203720472057206720772087209721072117212721372147215721672177218721972207221722272237224722572267227722872297230723172327233723472357236723772387239724072417242724372447245724672477248724972507251725272537254725572567257725872597260726172627263726472657266726772687269727072717272727372747275727672777278727972807281728272837284728572867287728872897290729172927293729472957296729772987299730073017302730373047305730673077308730973107311731273137314731573167317731873197320732173227323732473257326732773287329733073317332733373347335733673377338733973407341734273437344734573467347734873497350735173527353735473557356735773587359736073617362736373647365736673677368736973707371737273737374737573767377737873797380738173827383738473857386738773887389739073917392739373947395739673977398739974007401740274037404740574067407740874097410741174127413741474157416741774187419742074217422742374247425742674277428742974307431743274337434743574367437743874397440744174427443744474457446744774487449745074517452745374547455745674577458745974607461746274637464746574667467746874697470747174727473747474757476747774787479748074817482748374847485748674877488748974907491749274937494749574967497749874997500750175027503750475057506750775087509751075117512751375147515751675177518751975207521752275237524752575267527752875297530753175327533753475357536753775387539754075417542754375447545754675477548754975507551755275537554755575567557755875597560756175627563756475657566756775687569757075717572757375747575757675777578757975807581758275837584758575867587758875897590759175927593759475957596759775987599760076017602760376047605760676077608760976107611761276137614761576167617761876197620762176227623762476257626762776287629763076317632763376347635763676377638763976407641764276437644764576467647764876497650765176527653765476557656765776587659766076617662766376647665766676677668766976707671767276737674767576767677767876797680768176827683768476857686768776887689769076917692769376947695769676977698769977007701770277037704770577067707770877097710771177127713771477157716771777187719772077217722772377247725772677277728772977307731773277337734773577367737773877397740774177427743774477457746774777487749775077517752775377547755775677577758775977607761776277637764776577667767776877697770777177727773777477757776777777787779778077817782778377847785778677877788778977907791779277937794779577967797779877997800780178027803780478057806780778087809781078117812781378147815781678177818781978207821782278237824782578267827782878297830783178327833783478357836783778387839784078417842784378447845784678477848784978507851785278537854785578567857785878597860786178627863786478657866786778687869787078717872787378747875787678777878787978807881788278837884788578867887788878897890789178927893789478957896789778987899790079017902790379047905790679077908790979107911791279137914791579167917791879197920792179227923792479257926792779287929793079317932793379347935793679377938793979407941794279437944794579467947794879497950795179527953795479557956795779587959796079617962796379647965796679677968796979707971797279737974797579767977797879797980798179827983798479857986798779887989799079917992799379947995799679977998799980008001800280038004800580068007800880098010801180128013801480158016801780188019802080218022802380248025802680278028802980308031803280338034803580368037803880398040804180428043804480458046804780488049805080518052805380548055805680578058805980608061806280638064806580668067806880698070807180728073807480758076807780788079808080818082808380848085808680878088808980908091809280938094809580968097809880998100810181028103810481058106810781088109811081118112811381148115811681178118811981208121812281238124812581268127812881298130813181328133813481358136813781388139814081418142814381448145814681478148814981508151815281538154815581568157815881598160816181628163816481658166816781688169817081718172817381748175817681778178817981808181818281838184818581868187818881898190819181928193819481958196819781988199820082018202820382048205820682078208820982108211821282138214821582168217821882198220822182228223822482258226822782288229823082318232823382348235823682378238823982408241824282438244824582468247824882498250825182528253825482558256825782588259826082618262826382648265826682678268826982708271827282738274827582768277827882798280828182828283828482858286828782888289829082918292829382948295829682978298829983008301830283038304830583068307830883098310831183128313831483158316831783188319832083218322832383248325832683278328832983308331833283338334833583368337833883398340834183428343834483458346834783488349835083518352835383548355835683578358835983608361836283638364836583668367836883698370837183728373837483758376837783788379838083818382838383848385838683878388838983908391839283938394839583968397839883998400840184028403840484058406840784088409841084118412841384148415841684178418841984208421842284238424842584268427842884298430843184328433843484358436843784388439844084418442844384448445844684478448844984508451845284538454845584568457845884598460846184628463846484658466846784688469847084718472847384748475847684778478847984808481848284838484848584868487848884898490849184928493849484958496849784988499850085018502850385048505850685078508850985108511851285138514851585168517851885198520852185228523852485258526852785288529853085318532853385348535853685378538853985408541854285438544854585468547854885498550855185528553855485558556855785588559856085618562856385648565856685678568856985708571857285738574857585768577857885798580858185828583858485858586858785888589859085918592859385948595859685978598859986008601860286038604860586068607860886098610861186128613861486158616861786188619862086218622862386248625862686278628862986308631863286338634863586368637863886398640864186428643864486458646864786488649865086518652865386548655865686578658865986608661866286638664866586668667866886698670867186728673867486758676867786788679868086818682868386848685868686878688868986908691869286938694869586968697869886998700870187028703870487058706870787088709871087118712871387148715871687178718871987208721872287238724872587268727872887298730873187328733873487358736873787388739874087418742874387448745874687478748874987508751875287538754875587568757875887598760876187628763876487658766876787688769877087718772877387748775877687778778877987808781878287838784878587868787878887898790879187928793879487958796879787988799880088018802880388048805880688078808880988108811881288138814881588168817881888198820882188228823882488258826882788288829883088318832883388348835883688378838883988408841884288438844884588468847884888498850885188528853885488558856885788588859886088618862886388648865886688678868886988708871887288738874887588768877887888798880888188828883888488858886888788888889889088918892889388948895889688978898889989008901890289038904890589068907890889098910891189128913891489158916891789188919892089218922892389248925892689278928892989308931893289338934893589368937893889398940894189428943894489458946894789488949895089518952895389548955895689578958895989608961896289638964896589668967896889698970897189728973897489758976897789788979898089818982898389848985898689878988898989908991899289938994899589968997899889999000900190029003900490059006900790089009901090119012901390149015901690179018901990209021902290239024902590269027902890299030903190329033903490359036903790389039904090419042904390449045904690479048904990509051905290539054905590569057905890599060906190629063906490659066906790689069907090719072907390749075907690779078907990809081908290839084908590869087908890899090909190929093909490959096909790989099910091019102910391049105910691079108910991109111911291139114911591169117911891199120912191229123912491259126912791289129913091319132913391349135913691379138913991409141914291439144914591469147914891499150915191529153915491559156915791589159916091619162916391649165916691679168916991709171917291739174917591769177917891799180918191829183918491859186918791889189919091919192919391949195919691979198919992009201920292039204920592069207920892099210921192129213921492159216921792189219922092219222922392249225922692279228922992309231923292339234923592369237923892399240924192429243924492459246924792489249925092519252925392549255925692579258925992609261926292639264926592669267926892699270927192729273927492759276927792789279928092819282928392849285928692879288928992909291929292939294929592969297929892999300930193029303930493059306930793089309931093119312931393149315931693179318931993209321932293239324932593269327932893299330933193329333933493359336933793389339934093419342934393449345934693479348934993509351935293539354935593569357935893599360936193629363936493659366936793689369937093719372937393749375937693779378937993809381938293839384938593869387938893899390939193929393939493959396939793989399940094019402940394049405940694079408940994109411941294139414941594169417941894199420942194229423942494259426942794289429943094319432943394349435943694379438943994409441944294439444944594469447944894499450945194529453945494559456945794589459946094619462946394649465946694679468946994709471947294739474947594769477947894799480948194829483948494859486948794889489949094919492949394949495949694979498949995009501950295039504950595069507950895099510951195129513951495159516951795189519952095219522952395249525952695279528952995309531953295339534953595369537953895399540954195429543954495459546954795489549955095519552955395549555955695579558955995609561956295639564956595669567956895699570957195729573957495759576957795789579958095819582958395849585958695879588958995909591959295939594959595969597959895999600960196029603960496059606960796089609961096119612961396149615961696179618961996209621962296239624962596269627962896299630963196329633963496359636963796389639964096419642964396449645964696479648964996509651965296539654965596569657965896599660966196629663966496659666966796689669967096719672967396749675967696779678967996809681968296839684968596869687968896899690969196929693969496959696969796989699970097019702970397049705970697079708970997109711971297139714971597169717971897199720972197229723972497259726972797289729973097319732973397349735973697379738973997409741974297439744974597469747974897499750975197529753975497559756975797589759976097619762976397649765976697679768976997709771977297739774977597769777977897799780978197829783978497859786978797889789979097919792979397949795979697979798979998009801980298039804980598069807980898099810981198129813981498159816981798189819982098219822982398249825982698279828982998309831983298339834983598369837983898399840984198429843984498459846984798489849985098519852985398549855985698579858985998609861986298639864986598669867986898699870987198729873987498759876987798789879988098819882988398849885988698879888988998909891989298939894989598969897989898999900990199029903990499059906990799089909991099119912991399149915991699179918991999209921992299239924992599269927992899299930993199329933993499359936993799389939994099419942994399449945994699479948994999509951995299539954995599569957995899599960996199629963996499659966996799689969997099719972997399749975997699779978997999809981998299839984998599869987998899899990999199929993999499959996999799989999100001000110002100031000410005100061000710008100091001010011100121001310014100151001610017100181001910020100211002210023100241002510026100271002810029100301003110032100331003410035100361003710038100391004010041100421004310044100451004610047100481004910050100511005210053100541005510056100571005810059100601006110062100631006410065100661006710068100691007010071100721007310074100751007610077100781007910080100811008210083100841008510086100871008810089100901009110092100931009410095100961009710098100991010010101101021010310104101051010610107101081010910110101111011210113101141011510116101171011810119101201012110122101231012410125101261012710128101291013010131101321013310134101351013610137101381013910140101411014210143101441014510146101471014810149101501015110152101531015410155101561015710158101591016010161101621016310164101651016610167101681016910170101711017210173101741017510176101771017810179101801018110182101831018410185101861018710188101891019010191101921019310194101951019610197101981019910200102011020210203102041020510206102071020810209102101021110212102131021410215102161021710218102191022010221102221022310224102251022610227102281022910230102311023210233102341023510236102371023810239102401024110242102431024410245102461024710248102491025010251102521025310254102551025610257102581025910260102611026210263102641026510266102671026810269102701027110272102731027410275102761027710278102791028010281102821028310284102851028610287102881028910290102911029210293102941029510296102971029810299103001030110302103031030410305103061030710308103091031010311103121031310314103151031610317103181031910320103211032210323103241032510326103271032810329103301033110332103331033410335103361033710338103391034010341103421034310344103451034610347103481034910350103511035210353103541035510356103571035810359103601036110362103631036410365103661036710368103691037010371103721037310374103751037610377103781037910380103811038210383103841038510386103871038810389103901039110392103931039410395103961039710398103991040010401104021040310404104051040610407104081040910410104111041210413104141041510416104171041810419104201042110422104231042410425104261042710428104291043010431104321043310434104351043610437104381043910440104411044210443104441044510446104471044810449104501045110452104531045410455104561045710458104591046010461104621046310464104651046610467104681046910470104711047210473104741047510476104771047810479104801048110482104831048410485104861048710488104891049010491104921049310494104951049610497104981049910500105011050210503105041050510506105071050810509105101051110512105131051410515105161051710518105191052010521105221052310524105251052610527105281052910530105311053210533105341053510536105371053810539105401054110542105431054410545105461054710548105491055010551105521055310554105551055610557105581055910560105611056210563105641056510566105671056810569105701057110572105731057410575105761057710578105791058010581105821058310584105851058610587105881058910590105911059210593105941059510596105971059810599106001060110602106031060410605106061060710608106091061010611106121061310614106151061610617106181061910620106211062210623106241062510626106271062810629106301063110632106331063410635106361063710638106391064010641106421064310644106451064610647106481064910650106511065210653106541065510656106571065810659106601066110662106631066410665106661066710668106691067010671106721067310674106751067610677106781067910680106811068210683106841068510686106871068810689106901069110692106931069410695106961069710698106991070010701107021070310704107051070610707107081070910710107111071210713107141071510716107171071810719107201072110722107231072410725107261072710728107291073010731107321073310734107351073610737107381073910740107411074210743107441074510746107471074810749107501075110752107531075410755107561075710758107591076010761107621076310764107651076610767107681076910770107711077210773107741077510776107771077810779107801078110782107831078410785107861078710788107891079010791107921079310794107951079610797107981079910800108011080210803108041080510806108071080810809108101081110812108131081410815108161081710818108191082010821108221082310824108251082610827108281082910830108311083210833108341083510836108371083810839108401084110842108431084410845108461084710848108491085010851108521085310854108551085610857108581085910860108611086210863108641086510866108671086810869108701087110872108731087410875108761087710878108791088010881108821088310884108851088610887108881088910890108911089210893108941089510896108971089810899109001090110902109031090410905109061090710908109091091010911109121091310914109151091610917109181091910920109211092210923109241092510926109271092810929109301093110932109331093410935109361093710938109391094010941109421094310944109451094610947109481094910950109511095210953109541095510956109571095810959109601096110962109631096410965109661096710968109691097010971109721097310974109751097610977109781097910980109811098210983109841098510986109871098810989109901099110992109931099410995109961099710998109991100011001110021100311004110051100611007110081100911010110111101211013110141101511016110171101811019110201102111022110231102411025110261102711028110291103011031110321103311034110351103611037110381103911040110411104211043110441104511046110471104811049110501105111052110531105411055110561105711058110591106011061110621106311064110651106611067110681106911070110711107211073110741107511076110771107811079110801108111082110831108411085110861108711088110891109011091110921109311094110951109611097110981109911100111011110211103111041110511106111071110811109111101111111112111131111411115111161111711118111191112011121111221112311124111251112611127111281112911130111311113211133111341113511136111371113811139111401114111142111431114411145111461114711148111491115011151111521115311154111551115611157111581115911160111611116211163111641116511166111671116811169111701117111172111731117411175111761117711178111791118011181111821118311184111851118611187111881118911190111911119211193111941119511196111971119811199112001120111202112031120411205112061120711208112091121011211112121121311214112151121611217112181121911220112211122211223112241122511226112271122811229112301123111232112331123411235112361123711238112391124011241112421124311244112451124611247112481124911250112511125211253112541125511256112571125811259112601126111262112631126411265112661126711268112691127011271112721127311274112751127611277112781127911280112811128211283112841128511286112871128811289112901129111292112931129411295112961129711298112991130011301113021130311304113051130611307113081130911310113111131211313113141131511316113171131811319113201132111322113231132411325113261132711328113291133011331113321133311334113351133611337113381133911340113411134211343113441134511346113471134811349113501135111352113531135411355113561135711358113591136011361113621136311364113651136611367113681136911370113711137211373113741137511376113771137811379113801138111382113831138411385113861138711388113891139011391113921139311394113951139611397113981139911400114011140211403114041140511406114071140811409114101141111412114131141411415114161141711418114191142011421114221142311424114251142611427114281142911430114311143211433114341143511436114371143811439114401144111442114431144411445114461144711448114491145011451114521145311454114551145611457114581145911460114611146211463114641146511466114671146811469114701147111472114731147411475114761147711478114791148011481114821148311484114851148611487114881148911490114911149211493114941149511496114971149811499115001150111502115031150411505115061150711508115091151011511115121151311514115151151611517115181151911520115211152211523115241152511526115271152811529115301153111532115331153411535115361153711538115391154011541115421154311544115451154611547115481154911550115511155211553115541155511556115571155811559115601156111562115631156411565115661156711568115691157011571115721157311574115751157611577115781157911580115811158211583115841158511586115871158811589115901159111592115931159411595115961159711598115991160011601116021160311604116051160611607116081160911610116111161211613116141161511616116171161811619116201162111622116231162411625116261162711628116291163011631116321163311634116351163611637116381163911640116411164211643116441164511646116471164811649116501165111652116531165411655116561165711658116591166011661116621166311664116651166611667116681166911670116711167211673116741167511676116771167811679116801168111682116831168411685116861168711688116891169011691116921169311694116951169611697116981169911700117011170211703117041170511706117071170811709117101171111712117131171411715117161171711718117191172011721117221172311724117251172611727117281172911730117311173211733117341173511736117371173811739117401174111742117431174411745117461174711748117491175011751117521175311754117551175611757117581175911760117611176211763117641176511766117671176811769117701177111772117731177411775117761177711778117791178011781117821178311784117851178611787117881178911790117911179211793117941179511796117971179811799118001180111802118031180411805118061180711808118091181011811118121181311814118151181611817118181181911820118211182211823118241182511826118271182811829118301183111832118331183411835118361183711838118391184011841118421184311844118451184611847118481184911850118511185211853118541185511856118571185811859118601186111862118631186411865118661186711868118691187011871118721187311874118751187611877118781187911880118811188211883118841188511886118871188811889118901189111892118931189411895118961189711898118991190011901119021190311904119051190611907119081190911910119111191211913119141191511916119171191811919119201192111922119231192411925119261192711928119291193011931119321193311934119351193611937119381193911940119411194211943119441194511946119471194811949119501195111952119531195411955119561195711958119591196011961119621196311964119651196611967119681196911970119711197211973119741197511976119771197811979119801198111982119831198411985119861198711988119891199011991119921199311994119951199611997119981199912000120011200212003120041200512006120071200812009120101201112012120131201412015120161201712018120191202012021120221202312024120251202612027120281202912030120311203212033120341203512036120371203812039120401204112042120431204412045120461204712048120491205012051120521205312054120551205612057120581205912060120611206212063120641206512066120671206812069120701207112072120731207412075120761207712078120791208012081120821208312084120851208612087120881208912090120911209212093120941209512096120971209812099121001210112102121031210412105121061210712108121091211012111121121211312114121151211612117121181211912120121211212212123121241212512126121271212812129121301213112132121331213412135121361213712138121391214012141121421214312144121451214612147121481214912150121511215212153121541215512156121571215812159121601216112162121631216412165121661216712168121691217012171121721217312174121751217612177121781217912180121811218212183121841218512186121871218812189121901219112192121931219412195121961219712198121991220012201122021220312204122051220612207122081220912210122111221212213122141221512216122171221812219122201222112222122231222412225122261222712228122291223012231122321223312234122351223612237122381223912240122411224212243122441224512246122471224812249122501225112252122531225412255122561225712258122591226012261122621226312264122651226612267122681226912270122711227212273122741227512276122771227812279122801228112282122831228412285122861228712288122891229012291122921229312294122951229612297122981229912300123011230212303123041230512306123071230812309123101231112312123131231412315123161231712318123191232012321123221232312324123251232612327123281232912330123311233212333123341233512336123371233812339123401234112342123431234412345123461234712348123491235012351123521235312354123551235612357123581235912360123611236212363123641236512366123671236812369123701237112372123731237412375123761237712378123791238012381123821238312384123851238612387123881238912390123911239212393123941239512396123971239812399124001240112402124031240412405124061240712408124091241012411124121241312414124151241612417124181241912420124211242212423124241242512426124271242812429124301243112432124331243412435124361243712438124391244012441124421244312444124451244612447124481244912450124511245212453124541245512456124571245812459124601246112462124631246412465124661246712468124691247012471124721247312474124751247612477124781247912480124811248212483124841248512486124871248812489124901249112492124931249412495124961249712498124991250012501125021250312504125051250612507125081250912510125111251212513125141251512516125171251812519125201252112522125231252412525125261252712528125291253012531125321253312534125351253612537125381253912540125411254212543125441254512546125471254812549125501255112552125531255412555125561255712558125591256012561125621256312564125651256612567125681256912570125711257212573125741257512576125771257812579125801258112582125831258412585125861258712588125891259012591125921259312594125951259612597125981259912600126011260212603126041260512606126071260812609126101261112612126131261412615126161261712618126191262012621126221262312624126251262612627126281262912630126311263212633126341263512636126371263812639126401264112642126431264412645126461264712648126491265012651126521265312654126551265612657126581265912660126611266212663126641266512666126671266812669126701267112672126731267412675126761267712678126791268012681126821268312684126851268612687126881268912690126911269212693126941269512696126971269812699127001270112702127031270412705127061270712708127091271012711127121271312714127151271612717127181271912720127211272212723127241272512726127271272812729127301273112732127331273412735127361273712738127391274012741127421274312744127451274612747127481274912750127511275212753127541275512756127571275812759127601276112762127631276412765127661276712768127691277012771127721277312774127751277612777127781277912780127811278212783127841278512786127871278812789127901279112792127931279412795127961279712798127991280012801128021280312804128051280612807128081280912810128111281212813128141281512816128171281812819128201282112822128231282412825128261282712828128291283012831128321283312834128351283612837128381283912840128411284212843128441284512846128471284812849128501285112852128531285412855128561285712858128591286012861128621286312864128651286612867128681286912870128711287212873128741287512876128771287812879128801288112882128831288412885128861288712888128891289012891128921289312894128951289612897128981289912900129011290212903129041290512906129071290812909129101291112912129131291412915129161291712918129191292012921129221292312924129251292612927129281292912930129311293212933129341293512936129371293812939129401294112942129431294412945129461294712948129491295012951129521295312954129551295612957129581295912960129611296212963129641296512966129671296812969129701297112972129731297412975129761297712978129791298012981129821298312984129851298612987129881298912990129911299212993129941299512996129971299812999130001300113002130031300413005130061300713008130091301013011130121301313014130151301613017130181301913020130211302213023130241302513026130271302813029130301303113032130331303413035130361303713038130391304013041130421304313044130451304613047130481304913050130511305213053130541305513056130571305813059130601306113062130631306413065130661306713068130691307013071130721307313074130751307613077130781307913080130811308213083130841308513086130871308813089130901309113092130931309413095130961309713098130991310013101131021310313104131051310613107131081310913110131111311213113131141311513116131171311813119131201312113122131231312413125131261312713128131291313013131131321313313134131351313613137131381313913140131411314213143131441314513146131471314813149131501315113152131531315413155131561315713158131591316013161131621316313164131651316613167131681316913170131711317213173131741317513176131771317813179131801318113182131831318413185131861318713188131891319013191131921319313194131951319613197131981319913200132011320213203132041320513206132071320813209132101321113212132131321413215132161321713218132191322013221132221322313224132251322613227132281322913230132311323213233132341323513236132371323813239132401324113242132431324413245132461324713248132491325013251132521325313254132551325613257132581325913260132611326213263132641326513266132671326813269132701327113272132731327413275132761327713278132791328013281132821328313284132851328613287132881328913290132911329213293132941329513296132971329813299133001330113302133031330413305133061330713308133091331013311133121331313314133151331613317133181331913320133211332213323133241332513326133271332813329133301333113332133331333413335133361333713338133391334013341133421334313344133451334613347133481334913350133511335213353133541335513356133571335813359133601336113362133631336413365133661336713368133691337013371133721337313374133751337613377133781337913380133811338213383133841338513386133871338813389133901339113392133931339413395133961339713398133991340013401134021340313404134051340613407134081340913410134111341213413134141341513416134171341813419134201342113422134231342413425134261342713428134291343013431134321343313434134351343613437134381343913440134411344213443134441344513446134471344813449134501345113452134531345413455134561345713458134591346013461134621346313464134651346613467134681346913470134711347213473134741347513476134771347813479134801348113482134831348413485134861348713488134891349013491134921349313494134951349613497134981349913500135011350213503135041350513506135071350813509135101351113512135131351413515135161351713518135191352013521135221352313524135251352613527135281352913530135311353213533135341353513536135371353813539135401354113542135431354413545135461354713548135491355013551135521355313554135551355613557135581355913560135611356213563135641356513566135671356813569135701357113572135731357413575135761357713578135791358013581135821358313584135851358613587135881358913590135911359213593135941359513596135971359813599136001360113602136031360413605136061360713608136091361013611136121361313614136151361613617136181361913620136211362213623136241362513626136271362813629136301363113632136331363413635136361363713638136391364013641136421364313644136451364613647136481364913650136511365213653136541365513656136571365813659136601366113662136631366413665136661366713668136691367013671136721367313674136751367613677136781367913680136811368213683136841368513686136871368813689136901369113692136931369413695136961369713698136991370013701137021370313704137051370613707137081370913710137111371213713137141371513716137171371813719137201372113722137231372413725137261372713728137291373013731137321373313734137351373613737137381373913740137411374213743137441374513746137471374813749137501375113752137531375413755137561375713758137591376013761137621376313764137651376613767137681376913770137711377213773137741377513776137771377813779137801378113782137831378413785137861378713788137891379013791137921379313794137951379613797137981379913800138011380213803138041380513806138071380813809138101381113812138131381413815138161381713818138191382013821138221382313824138251382613827138281382913830138311383213833138341383513836138371383813839138401384113842138431384413845138461384713848138491385013851138521385313854138551385613857138581385913860138611386213863138641386513866138671386813869138701387113872138731387413875138761387713878138791388013881138821388313884138851388613887138881388913890138911389213893138941389513896138971389813899139001390113902139031390413905139061390713908139091391013911139121391313914139151391613917139181391913920139211392213923139241392513926139271392813929139301393113932139331393413935139361393713938139391394013941139421394313944139451394613947139481394913950139511395213953139541395513956139571395813959139601396113962139631396413965139661396713968139691397013971139721397313974139751397613977139781397913980139811398213983139841398513986139871398813989139901399113992139931399413995139961399713998139991400014001140021400314004140051400614007140081400914010140111401214013140141401514016140171401814019140201402114022140231402414025140261402714028140291403014031140321403314034140351403614037140381403914040140411404214043140441404514046140471404814049140501405114052140531405414055140561405714058140591406014061140621406314064140651406614067140681406914070140711407214073140741407514076140771407814079140801408114082140831408414085140861408714088140891409014091140921409314094140951409614097140981409914100141011410214103141041410514106141071410814109141101411114112141131411414115141161411714118141191412014121141221412314124141251412614127141281412914130141311413214133141341413514136141371413814139141401414114142141431414414145141461414714148141491415014151141521415314154141551415614157141581415914160141611416214163141641416514166141671416814169141701417114172141731417414175141761417714178141791418014181141821418314184141851418614187141881418914190141911419214193141941419514196141971419814199142001420114202142031420414205142061420714208142091421014211142121421314214142151421614217142181421914220142211422214223142241422514226142271422814229142301423114232142331423414235142361423714238142391424014241142421424314244142451424614247142481424914250142511425214253142541425514256142571425814259142601426114262142631426414265142661426714268142691427014271142721427314274142751427614277142781427914280142811428214283142841428514286142871428814289142901429114292142931429414295142961429714298142991430014301143021430314304143051430614307143081430914310143111431214313143141431514316143171431814319143201432114322143231432414325143261432714328143291433014331143321433314334143351433614337143381433914340143411434214343143441434514346143471434814349143501435114352143531435414355143561435714358143591436014361143621436314364143651436614367143681436914370143711437214373143741437514376143771437814379143801438114382143831438414385143861438714388143891439014391143921439314394143951439614397143981439914400144011440214403144041440514406144071440814409144101441114412144131441414415144161441714418144191442014421144221442314424144251442614427144281442914430144311443214433144341443514436144371443814439144401444114442144431444414445144461444714448144491445014451144521445314454144551445614457144581445914460144611446214463144641446514466144671446814469144701447114472144731447414475144761447714478144791448014481144821448314484144851448614487144881448914490144911449214493144941449514496144971449814499145001450114502145031450414505145061450714508145091451014511145121451314514145151451614517145181451914520145211452214523145241452514526145271452814529145301453114532145331453414535145361453714538145391454014541145421454314544145451454614547145481454914550145511455214553145541455514556145571455814559145601456114562145631456414565145661456714568145691457014571145721457314574145751457614577145781457914580145811458214583145841458514586145871458814589145901459114592145931459414595145961459714598145991460014601146021460314604146051460614607146081460914610146111461214613146141461514616146171461814619146201462114622146231462414625146261462714628146291463014631146321463314634146351463614637146381463914640146411464214643146441464514646146471464814649146501465114652146531465414655146561465714658146591466014661146621466314664146651466614667146681466914670146711467214673146741467514676146771467814679146801468114682146831468414685146861468714688146891469014691146921469314694146951469614697146981469914700147011470214703147041470514706147071470814709147101471114712147131471414715147161471714718147191472014721147221472314724147251472614727147281472914730147311473214733147341473514736147371473814739147401474114742147431474414745147461474714748147491475014751147521475314754147551475614757147581475914760147611476214763147641476514766147671476814769147701477114772147731477414775147761477714778147791478014781147821478314784147851478614787147881478914790147911479214793147941479514796147971479814799148001480114802148031480414805148061480714808148091481014811148121481314814148151481614817148181481914820148211482214823148241482514826148271482814829148301483114832148331483414835148361483714838148391484014841148421484314844148451484614847148481484914850148511485214853148541485514856148571485814859148601486114862148631486414865148661486714868148691487014871148721487314874148751487614877148781487914880148811488214883148841488514886148871488814889148901489114892148931489414895148961489714898148991490014901149021490314904149051490614907149081490914910149111491214913149141491514916149171491814919149201492114922149231492414925149261492714928149291493014931149321493314934149351493614937149381493914940149411494214943149441494514946149471494814949149501495114952149531495414955149561495714958149591496014961149621496314964149651496614967149681496914970149711497214973149741497514976149771497814979149801498114982149831498414985149861498714988149891499014991149921499314994149951499614997149981499915000150011500215003150041500515006150071500815009150101501115012150131501415015150161501715018150191502015021150221502315024150251502615027150281502915030150311503215033150341503515036150371503815039150401504115042150431504415045150461504715048150491505015051150521505315054150551505615057150581505915060150611506215063150641506515066150671506815069150701507115072150731507415075150761507715078150791508015081150821508315084150851508615087150881508915090150911509215093150941509515096150971509815099151001510115102151031510415105151061510715108151091511015111151121511315114151151511615117151181511915120151211512215123151241512515126151271512815129151301513115132151331513415135151361513715138151391514015141151421514315144151451514615147151481514915150151511515215153151541515515156151571515815159151601516115162151631516415165151661516715168151691517015171151721517315174151751517615177151781517915180151811518215183151841518515186151871518815189151901519115192151931519415195151961519715198151991520015201152021520315204152051520615207152081520915210152111521215213152141521515216152171521815219152201522115222152231522415225152261522715228152291523015231152321523315234152351523615237152381523915240152411524215243152441524515246152471524815249152501525115252152531525415255152561525715258152591526015261152621526315264152651526615267152681526915270152711527215273152741527515276152771527815279152801528115282152831528415285152861528715288152891529015291152921529315294152951529615297152981529915300153011530215303153041530515306153071530815309153101531115312153131531415315153161531715318153191532015321153221532315324153251532615327153281532915330153311533215333153341533515336153371533815339153401534115342153431534415345153461534715348153491535015351153521535315354153551535615357153581535915360153611536215363153641536515366153671536815369153701537115372153731537415375153761537715378153791538015381153821538315384153851538615387153881538915390153911539215393153941539515396153971539815399154001540115402154031540415405154061540715408154091541015411154121541315414154151541615417154181541915420154211542215423154241542515426154271542815429154301543115432154331543415435154361543715438154391544015441154421544315444154451544615447154481544915450154511545215453154541545515456154571545815459154601546115462154631546415465154661546715468154691547015471154721547315474154751547615477154781547915480154811548215483154841548515486154871548815489154901549115492154931549415495154961549715498154991550015501155021550315504155051550615507155081550915510155111551215513155141551515516155171551815519155201552115522155231552415525155261552715528155291553015531155321553315534155351553615537155381553915540155411554215543155441554515546155471554815549155501555115552155531555415555155561555715558155591556015561155621556315564155651556615567155681556915570155711557215573155741557515576155771557815579155801558115582155831558415585155861558715588155891559015591155921559315594155951559615597155981559915600156011560215603156041560515606156071560815609156101561115612156131561415615156161561715618156191562015621156221562315624156251562615627156281562915630156311563215633156341563515636156371563815639156401564115642156431564415645156461564715648156491565015651156521565315654156551565615657156581565915660156611566215663156641566515666156671566815669156701567115672156731567415675156761567715678156791568015681156821568315684156851568615687156881568915690156911569215693156941569515696156971569815699157001570115702157031570415705157061570715708157091571015711157121571315714157151571615717157181571915720157211572215723157241572515726157271572815729157301573115732157331573415735157361573715738157391574015741157421574315744157451574615747157481574915750157511575215753157541575515756157571575815759157601576115762157631576415765157661576715768157691577015771157721577315774157751577615777157781577915780157811578215783157841578515786157871578815789157901579115792157931579415795157961579715798157991580015801158021580315804158051580615807158081580915810158111581215813158141581515816158171581815819158201582115822158231582415825158261582715828158291583015831158321583315834158351583615837158381583915840158411584215843158441584515846158471584815849158501585115852158531585415855158561585715858158591586015861158621586315864158651586615867158681586915870158711587215873158741587515876158771587815879158801588115882158831588415885158861588715888158891589015891158921589315894158951589615897158981589915900159011590215903159041590515906159071590815909159101591115912159131591415915159161591715918159191592015921159221592315924159251592615927159281592915930159311593215933159341593515936159371593815939159401594115942159431594415945159461594715948159491595015951159521595315954159551595615957159581595915960159611596215963159641596515966159671596815969159701597115972159731597415975159761597715978159791598015981159821598315984159851598615987159881598915990159911599215993159941599515996159971599815999160001600116002160031600416005160061600716008160091601016011160121601316014160151601616017160181601916020160211602216023160241602516026160271602816029160301603116032160331603416035160361603716038160391604016041160421604316044160451604616047160481604916050160511605216053160541605516056160571605816059160601606116062160631606416065160661606716068160691607016071160721607316074160751607616077160781607916080160811608216083160841608516086160871608816089160901609116092160931609416095160961609716098160991610016101161021610316104161051610616107161081610916110161111611216113161141611516116161171611816119161201612116122161231612416125161261612716128161291613016131161321613316134161351613616137161381613916140161411614216143161441614516146161471614816149161501615116152161531615416155161561615716158161591616016161161621616316164161651616616167161681616916170161711617216173161741617516176161771617816179161801618116182161831618416185161861618716188161891619016191161921619316194161951619616197161981619916200162011620216203162041620516206162071620816209162101621116212162131621416215162161621716218162191622016221162221622316224162251622616227162281622916230162311623216233162341623516236162371623816239162401624116242162431624416245162461624716248162491625016251162521625316254162551625616257162581625916260162611626216263162641626516266162671626816269162701627116272162731627416275162761627716278162791628016281162821628316284162851628616287162881628916290162911629216293162941629516296162971629816299163001630116302163031630416305163061630716308163091631016311163121631316314163151631616317163181631916320163211632216323163241632516326163271632816329163301633116332163331633416335163361633716338163391634016341163421634316344163451634616347163481634916350163511635216353163541635516356163571635816359163601636116362163631636416365163661636716368163691637016371163721637316374163751637616377163781637916380163811638216383163841638516386163871638816389163901639116392163931639416395163961639716398163991640016401164021640316404164051640616407164081640916410164111641216413164141641516416164171641816419164201642116422164231642416425164261642716428164291643016431164321643316434164351643616437164381643916440164411644216443164441644516446164471644816449164501645116452164531645416455164561645716458164591646016461164621646316464164651646616467164681646916470164711647216473164741647516476164771647816479164801648116482164831648416485164861648716488164891649016491164921649316494164951649616497164981649916500165011650216503165041650516506165071650816509165101651116512165131651416515165161651716518165191652016521165221652316524165251652616527165281652916530165311653216533165341653516536165371653816539165401654116542165431654416545165461654716548165491655016551165521655316554165551655616557165581655916560165611656216563165641656516566165671656816569165701657116572165731657416575165761657716578165791658016581165821658316584165851658616587165881658916590165911659216593165941659516596165971659816599166001660116602166031660416605166061660716608166091661016611166121661316614166151661616617166181661916620166211662216623166241662516626166271662816629166301663116632166331663416635166361663716638166391664016641166421664316644166451664616647166481664916650166511665216653166541665516656166571665816659166601666116662166631666416665166661666716668166691667016671166721667316674166751667616677166781667916680166811668216683166841668516686166871668816689166901669116692166931669416695166961669716698166991670016701167021670316704167051670616707167081670916710167111671216713167141671516716167171671816719167201672116722167231672416725167261672716728167291673016731167321673316734167351673616737167381673916740167411674216743167441674516746167471674816749167501675116752167531675416755167561675716758167591676016761167621676316764167651676616767167681676916770167711677216773167741677516776167771677816779167801678116782167831678416785167861678716788167891679016791167921679316794167951679616797167981679916800168011680216803168041680516806168071680816809168101681116812168131681416815168161681716818168191682016821168221682316824168251682616827168281682916830168311683216833168341683516836168371683816839168401684116842168431684416845168461684716848168491685016851168521685316854168551685616857168581685916860168611686216863168641686516866168671686816869168701687116872168731687416875168761687716878168791688016881168821688316884168851688616887168881688916890168911689216893168941689516896168971689816899169001690116902169031690416905169061690716908169091691016911169121691316914169151691616917169181691916920169211692216923169241692516926169271692816929169301693116932169331693416935169361693716938169391694016941169421694316944169451694616947169481694916950169511695216953169541695516956169571695816959169601696116962169631696416965169661696716968169691697016971169721697316974169751697616977169781697916980169811698216983169841698516986169871698816989169901699116992169931699416995169961699716998169991700017001170021700317004170051700617007170081700917010170111701217013170141701517016170171701817019170201702117022170231702417025170261702717028170291703017031170321703317034170351703617037
  1. The Kermit Project
  2. Columbia University
  3. 612 West 115th Street
  4. New York NY 10025 USA
  5. kermit@columbia.edu
  6. ...since 1981
  7. Supplement to Using C-Kermit, 2nd Edition
  8. For C-Kermit 7.0
  9. As of C-Kermit version: 7.0.196
  10. This file created: 8 February 2000
  11. This file last updated:
  12. Mon Aug 8 10:39:18 2011
  13. Authors: Frank da Cruz and Christine M. Gianone
  14. Address: The Kermit Project
  15. Columbia University
  16. 612 West 115th Street
  17. New York NY 10025-7799
  18. USA
  19. Fax: +1 (212) 662-6442
  20. E-Mail: kermit-support@columbia.edu
  21. Web: http://www.columbia.edu/kermit/
  22. Or: http://www.kermit-project.org/
  23. Or: http://www.columbia.nyc.ny.us/kermit/
  24. NOTICES
  25. This document:
  26. Copyright © 1997, 2000, Frank da Cruz and Christine M. Gianone.
  27. All rights reserved.
  28. Kermit 95:
  29. Copyright © 1995, 2000, Trustees of Columbia University in the
  30. City of New York. All rights reserved.
  31. C-Kermit:
  32. Copyright © 1985, 2000,
  33. Trustees of Columbia University in the City of New York. All
  34. rights reserved. See the C-KermitCOPYING.TXT file or the
  35. copyright text in theckcmai.c module for disclaimer and
  36. permissions.
  37. When Kerberos(TM) and/or SRP(TM) (Secure Remote Password) and/or SSL
  38. protocol are included:
  39. Portions Copyright © 1990, Massachusetts Institute of
  40. Technology.
  41. Portions Copyright © 1991, 1993 Regents of the University of
  42. California.
  43. Portions Copyright © 1991, 1992, 1993, 1994, 1995 by AT&T.
  44. Portions Copyright © 1997, Stanford University.
  45. Portions Copyright © 1995-1997, Eric Young <eay@cryptosoft.com>.
  46. For the full text of the third-party copyright notices, see
  47. Appendix V.
  48. WHAT IS IN THIS FILE
  49. This file lists changes made to C-Kermit since the second edition of
  50. the bookUsing C-Kermit was published and C-Kermit 6.0 was released
  51. in November 1996. Use this file as a supplement to the second edition
  52. of Using C-Kermit until the third edition is published some time in
  53. 2000. If the "most recent update" shown above is long ago, contact
  54. Columbia University to see if there is a newer release.
  55. For further information, also see theCKCBWR.TXT ("C-Kermit
  56. beware") file for hints, tips, tricks, restrictions, frequently asked
  57. questions, etc, plus the system-specific "beware file", e.g.
  58. CKUBWR.TXT for UNIX,CKVBWR.TXT for VMS, etc, and also any
  59. system-specific update files such as KERMIT95.HTM for Kermit 95 (in the
  60. DOCS\MANUAL\ subdirectory of your K95 directory).
  61. This Web-based copy of the C-Kermit 7.0 update notes supersedes the
  62. plain-text CKERMIT2.TXT file. All changes after 19 January 2000
  63. appear only here in the Web version. If you need an up-to-date
  64. plain-text copy, use your Web browser to save this page as plain
  65. text.
  66. ABOUT FILENAMES
  67. In this document, filenames are generally shown in uppercase, but on
  68. file systems with case-sensitive names such as UNIX, OS-9, and AOS/VS,
  69. lowercase names are used:ckubwr.txt,ckermit70.txt, etc.
  70. ADDITIONAL FILES
  71. Several other files accompany this new Kermit release:
  72. SECURITY.TXT
  73. Discussion of Kermit's new authentication and encryption
  74. features:
  75. +Plain-text version
  76. +HTML (hypertext) version
  77. IKSD.TXT
  78. How to install and manage an Internet Kermit Service Daemon.
  79. +Plain-text version
  80. +HTML (hypertext) version
  81. Also seecuiksd.htm for instructions for use.
  82. TELNET.TXT
  83. A thorough presentation of Kermit's new advanced Telnet features
  84. and controls.
  85. +Plain-text version
  86. +HTML (hypertext) version
  87. THE NEW C-KERMIT LICENSE
  88. The C-Kermit license was rewritten for version 7.0 to grant automatic
  89. permission to packagers of free operating-system distributions to
  90. include C-Kermit 7.0. Examples include Linux (GNU/Linux), FreeBSD,
  91. NetBSD, etc. The new license is in theCOPYING.TXT file, and is
  92. also displayed by C-Kermit itself when you give the VERSION or
  93. COPYRIGHT command. The new C-Kermit license does not apply to
  94. Kermit 95.
  95. ACKNOWLEDGMENTS
  96. Thanks to Jeff Altman, who joined the Kermit Project in 1995, for much
  97. of what you see in C-Kermit 7.0, especially in the networking and
  98. security areas, and his key role in designing and implementing the
  99. Internet Kermit Service Daemon. And special thanks to Lucas Hart for
  100. lots of help with the VMS version; to Peter Eichhorn for continuous
  101. testing on the full range of HP-UX versions and for a consolidated set
  102. of HP-UX makefile targets; and to Colin Allen, Mark Allen, Roger Allen,
  103. Ric Anderson, William Bader, Mitch Baker, Mitchell Bass, Nelson Beebe,
  104. Gerry Belanger, Jeff Bernsten, Mark Berryman, John Bigg, Volker
  105. Borchert, Jonathan Boswell, Tim Boyer, Frederick Bruckman, Kenneth
  106. Cochran, Jared Crapo, Bill Delaney, Igor Sobrado Delgado, Clarence
  107. Dold, Joe Doupnik, John Dunlap, Max Evarts, Patrick French, Carl
  108. Friedberg, Carl Friend, Hirofumi Fujii, Andrew Gabriel, Gabe Garza,
  109. Boyd Gerber, David Gerber, George Gilmer, Hunter Goatley, DJ Hagberg,
  110. Kevin Handy, Andy Harper, Randolph Herber, Sven Holström, Michal
  111. Jaegermann, Graham Jenkins, Dick Jones, Terry Kennedy, Robert D Keys,
  112. Nick Kisseberth, Igor Kovalenko, David Lane, Adam Laurie, Jeff
  113. Liebermann, Eric Lonvick, Hoi Wan Louis, Arthur Marsh, Gregorie Martin,
  114. Peter Mauzey, Dragan Milicic, Todd Miller, Christian Mondrup, Daniel
  115. Morato, Dat Nguyen, Herb Peyerl, Jean-Pierre Radley, Steve Rance,
  116. Stephen Riehm, Nigel Roles, Larry Rosenman, Jay S Rouman, David
  117. Sanderson, John Santos, Michael Schmitz, Steven Schultz, Bob Shair,
  118. Richard Shuford, Fred Smith, Michael Sokolov, Jim Spath, Peter Szell,
  119. Ted T'so, Brian Tillman, Linus Torvalds, Patrick Volkerding, Martin
  120. Vorländer, Steve Walton, Ken Weaverling, John Weekley, Martin Whitaker,
  121. Jim Whitby, Matt Willman, Joellen Windsor, Farrell Woods, and many
  122. others for binaries, hosting, reviews, suggestions, advice, bug
  123. reports, and all the rest over the 3+ year C-Kermit 7.0 development
  124. cycle. Thanks to Russ Nelson and the board of the Open Software
  125. Initiative (http://www.opensource.org) for their cooperation in
  126. developing the new C-Kermit license and to the proprietors of those
  127. free UNIX distributions that have incorporated C-Kermit 7.0 for their
  128. cooperation and support, especially FreeBSD's Jörg Wunsch.
  129. NOTE TO KERMIT 95 USERS
  130. Kermit 95 and C-Kermit share the same command and scripting language,
  131. the same Kermit file-transfer protocol implementation, and much else
  132. besides.
  133. Like the bookUsing C-Kermit, this file concentrates on the aspects
  134. of C-Kermit that are common to all versions: UNIX, VMS, Windows, OS/2,
  135. VOS, AOS/VS, etc. Please refer to your Kermit 95 documentation for
  136. information that is specific to Kermit 95.
  137. C-Kermit 7.0 corresponds to Kermit 95 1.1.19.
  138. C-KERMIT VERSIONS AND VERSION NUMBERS
  139. "C-Kermit" refers to all the many programs that are compiled in whole
  140. or in part from common C-language source code, comprising:
  141. * A Kermit file transfer protocol module
  142. * A command parser and script execution module
  143. * A modem-dialing module
  144. * A network support module
  145. * A character-set translation module.
  146. and several others. These "system-independent" modules are combined
  147. with system-dependent modules for each platform to provide the required
  148. input/output functions, and also in some cases overlaid with an
  149. alternative user interface, such as Macintosh Kermit's point-and-click
  150. interface, and in some cases also a terminal emulator, as Kermit 95.
  151. The C-Kermit version number started as 1.0, ... 3.0, 4.0, 4.1 and then
  152. (because of confusion at the time with Berkeley UNIX 4.2), 4B, 4C, and
  153. so on, with the specific edit number in parentheses, for example
  154. 4E(072) or 5A(188). This scheme was used through 5A(191), but now we
  155. have gone back to the traditional numbering scheme with decimal points:
  156. major.minor.edit; for example 7.0.196. Internal version numbers (the
  157. \v(version) variable), however, are compatible in C-Kermit 5A upwards.
  158. Meanwhile, C-Kermit derivatives for some platforms (Windows, Macintosh)
  159. might go through several releases while C-Kermit itself remains the
  160. same. These versions have their own platform-specific version numbers,
  161. such as Kermit 95 1.1.1, 1.1.2, and so on.
  162. C-Kermit Version History:
  163. 1.0 1981-1982 Command-line only, 4.2 BSD UNIX only
  164. 2.0 (*) (who remembers...)
  165. 3.0 May 1984 Command-line only, supports several platforms
  166. 4.0-4.1 Feb-Apr 1985 (*) First interactive and modular version
  167. 4C(050) May 1985
  168. 4D(060) April 1986
  169. 4E(066) August 1987 Long packets
  170. 4E(068) January 1988
  171. 4E(072) January 1989
  172. 4F(095) August 1989 (*) Attribute packets
  173. 5A(188) November 1992 Scripting, TCP/IP, sliding windows (1)
  174. 5A(189) September 1993 Control-char unprefixing
  175. 5A(190) October 1994 Recovery
  176. 5A(191) April 1995 OS/2 only
  177. 6.0.192 September 1996 Intelligent dialing, autodownload, lots more (2)
  178. 6.1.193 1997-98 (*) Development only
  179. 6.1.194 June 1998 K95 only - switches, directory recursion, more
  180. 7.0.195 August 1999 IKSD + more (CU only as K95 1.1.18-CU)
  181. 7.0.196 1 January 2000 Unicode, lots more
  182. (*) Never formally released (4.0 was a total rewrite)
  183. (1) Using C-Kermit, 1st Edition
  184. (2) Using C-Kermit, 2nd Edition
  185. CONTENTS
  186. I. C-KERMIT DOCUMENTATION
  187. II. NEW FEATURES
  188. (0) INCOMPATIBILITIES WITH PREVIOUS RELEASES
  189. (1) PROGRAM AND FILE MANAGEMENT AND COMMANDS
  190. 1.0. Bug fixes
  191. 1.1. Command Continuation
  192. 1.2. Editor Interface
  193. 1.3. Web Browser and FTP Interface
  194. 1.4. Command Editing
  195. 1.5. Command Switches
  196. 1.5.1. General Switch Syntax
  197. 1.5.2. Order and Effect of Switches
  198. 1.5.3. Distinguishing Switches from Other Fields
  199. 1.5.4. Standard File Selection Switches
  200. 1.5.5. Setting Preferences for Different Commands
  201. 1.6. Dates and Times
  202. 1.7. Partial Completion of Keywords
  203. 1.8. Command Recall
  204. 1.9. EXIT Messages
  205. 1.10. Managing Keyboard Interruptions
  206. 1.11. Taming the Wild Backslash -- Part Deux
  207. 1.11.1. Background
  208. 1.11.2. Kermit's Quoting Rules
  209. 1.11.3. Passing DOS Filenames from Kermit to Shell Commands
  210. 1.11.4. Using Variables to Hold DOS Filenames
  211. 1.11.5. Passing DOS Filenames as Parameters to Macros
  212. 1.11.6. Passing DOS File Names from Macro Parameters to
  213. the DOS Shell
  214. 1.11.7. Passing DOS Filenames to Kermit from the Shell
  215. 1.12. Debugging
  216. 1.13. Logs
  217. 1.14. Automatic File-Transfer Packet Recognition at
  218. the Command Prompt
  219. 1.15. The TYPE Command
  220. 1.16. The RESET Command
  221. 1.17. The COPY and RENAME Commands
  222. 1.18. The MANUAL Command
  223. 1.19. String and Filename Matching Patterns
  224. 1.20. Multiple Commands on One Line
  225. 1.21. What Do I Have?
  226. 1.22. Generalized File Input and Output
  227. 1.22.1. Why Another I/O System?
  228. 1.22.2. The FILE Command
  229. 1.22.3. FILE Command Examples
  230. 1.22.4. Channel Numbers
  231. 1.22.5. FILE Command Error Codes
  232. 1.22.6. File I/O Variables
  233. 1.22.7. File I/O Functions
  234. 1.22.8. File I/O Function Examples
  235. 1.23. The EXEC Command
  236. 1.24. Getting Keyword Lists with '?'
  237. (2) MAKING AND USING CONNECTIONS
  238. 2.0. SET LINE and SET HOST Command Switches
  239. 2.1. Dialing
  240. 2.1.1. The Dial Result Message
  241. 2.1.2. Long-Distance Dialing Changes
  242. 2.1.3. Forcing Long-Distance Dialing
  243. 2.1.4. Exchange-Specific Dialing Decisions
  244. 2.1.5. Cautions about Cheapest-First Dialing
  245. 2.1.6. Blind Dialing (Dialing with No Dialtone)
  246. 2.1.7. Trimming the Dialing Dialog
  247. 2.1.8. Controlling the Dialing Speed
  248. 2.1.9. Pretesting Phone Number Conversions
  249. 2.1.10. Greater Control over Partial Dialing
  250. 2.1.11. New DIAL-related Variables and Functions
  251. 2.1.12. Increased Flexibility of PBX Dialing
  252. 2.1.13. The DIAL macro - Last-Minute Phone Number Conversions
  253. 2.1.14. Automatic Tone/Pulse Dialing Selection
  254. 2.1.15. Dial-Modifier Variables
  255. 2.1.16. Giving Multiple Numbers to the DIAL Command
  256. 2.2. Modems
  257. 2.2.1. New Modem Types
  258. 2.2.2. New Modem Controls
  259. 2.3.TELNET and RLOGIN
  260. 2.3.0. Bug Fixes
  261. 2.3.1. Telnet Binary Mode Bug Adjustments
  262. 2.3.2. VMS UCX Telnet Port Bug Adjustment
  263. 2.3.3. Telnet New Environment Option
  264. 2.3.4. Telnet Location Option
  265. 2.3.5. Connecting to Raw TCP Sockets
  266. 2.3.6. Incoming TCP Connections
  267. 2.4. The EIGHTBIT Command
  268. 2.5. The Services Directory
  269. 2.6. Closing Connections
  270. 2.7. Using C-Kermit with External Communication Programs
  271. 2.7.0. C-Kermit over tn3270 and tn5250
  272. 2.7.1. C-Kermit over Telnet
  273. 2.7.2. C-Kermit over Rlogin
  274. 2.7.3. C-Kermit over Serial Communication Programs
  275. 2.7.4. C-Kermit over Secure Network Clients
  276. 2.7.4.1. SSH
  277. 2.7.4.2. SSL
  278. 2.7.4.3. SRP
  279. 2.7.4.4. SOCKS
  280. 2.7.4.5. Kerberos and SRP
  281. 2.8. Scripting Local Programs
  282. 2.9. X.25 Networking
  283. 2.9.1. IBM AIXLink/X.25 Network Provider Interface for AIX
  284. 2.9.2. HP-UX X.25
  285. 2.10. Additional Serial Port Controls
  286. 2.11. Getting Access to the Dialout Device
  287. 2.12. The Connection Log
  288. 2.13. Automatic Connection-Specific Flow Control Selection
  289. 2.14. Trapping Connection Establishment and Loss
  290. 2.15. Contacting Web Servers with the HTTP Command
  291. (3) TERMINAL CONNECTION
  292. 3.1. CONNECT Command Switches
  293. 3.2. Triggers
  294. 3.3. Transparent Printing
  295. 3.4. Binary and Text Session Logs
  296. (4) FILE TRANSFER AND MANAGEMENT
  297. 4.0. Bug Fixes, Minor Changes, and Clarifications
  298. 4.1. File-Transfer Filename Templates
  299. 4.1.1. Templates in the As-Name
  300. 4.1.2. Templates on the Command Line
  301. 4.1.3. Post-Transfer Renaming
  302. 4.2. File-Transfer Pipes and Filters
  303. 4.2.1. Introduction
  304. 4.2.1.1. Terminology
  305. 4.2.1.2. Notation
  306. 4.2.1.3. Security
  307. 4.2.2. Commands for Transferring from and to Pipes
  308. 4.2.2.1. Sending from a Command
  309. 4.2.2.2. Receiving to a Command
  310. 4.2.3. Using File-Transfer Filters
  311. 4.2.3.1. The SEND Filter
  312. 4.2.3.2. The RECEIVE Filter
  313. 4.2.4. Implicit Use of Pipes
  314. 4.2.5. Success and Failure of Piped Commands
  315. 4.2.6. Cautions about Using Pipes to Transfer Directory Trees
  316. 4.2.7. Pipes and Encryption
  317. 4.2.8. Commands and Functions Related to Pipes
  318. 4.2.8.1. The OPEN !READ and OPEN !WRITE Commands
  319. 4.2.8.2. The REDIRECT Command
  320. 4.2.8.3. Receiving Mail and Print Jobs
  321. 4.2.8.4. Pipe-Related Functions
  322. 4.3. Automatic Per-File Text/Binary Mode Switching
  323. 4.3.1. Exceptions
  324. 4.3.2. Overview
  325. 4.3.3. Commands
  326. 4.3.4. Examples
  327. 4.4. File Permissions
  328. 4.4.1. When ATTRIBUTES PROTECTION is OFF
  329. 4.4.1.1. Unix
  330. 4.4.1.2. VMS
  331. 4.4.2. When ATTRIBUTES PROTECTION is ON
  332. 4.4.2.1. System-Specific Permissions
  333. 4.4.2.1.1. UNIX
  334. 4.4.2.1.2. VMS
  335. 4.4.2.2. System-Independent Permissions
  336. 4.5. File Management Commands
  337. 4.5.1. The DIRECTORY Command
  338. 4.5.2. The CD and BACK Commands
  339. 4.5.2.1. Parsing Improvements
  340. 4.5.2.2. The CDPATH
  341. 4.5.3. Creating and Removing Directories
  342. 4.5.4. The DELETE and PURGE Commands
  343. 4.6. Starting the Remote Kermit Server Automatically
  344. 4.7. File-Transfer Command Switches
  345. 4.7.1. SEND Command Switches
  346. 4.7.2. GET Command Switches
  347. 4.7.3. RECEIVE Command Switches
  348. 4.8. Minor Kermit Protocol Improvements
  349. 4.8.1. Multiple Attribute Packets
  350. 4.8.2. Very Short Packets
  351. 4.9. Wildcard / File Group Expansion
  352. 4.9.1. In UNIX C-Kermit
  353. 4.9.2. In Kermit 95
  354. 4.9.3. In VMS, AOS/VS, OS-9, VOS, etc.
  355. 4.10. Additional Pathname Controls
  356. 4.11. Recursive SEND and GET: Transferring Directory Trees
  357. 4.11.1. Command-Line Options
  358. 4.11.2. The SEND /RECURSIVE Command
  359. 4.11.3. The GET /RECURSIVE Command
  360. 4.11.4. New and Changed File Functions
  361. 4.11.5. Moving Directory Trees Between Like Systems
  362. 4.11.6. Moving Directory Trees Between Unlike Systems
  363. 4.12. Where Did My File Go?
  364. 4.13. File Output Buffer Control
  365. 4.14. Improved Responsiveness
  366. 4.15. Doubling and Ignoring Characters for Transparency
  367. 4.16. New File-Transfer Display Formats
  368. 4.17. New Transaction Log Formats
  369. 4.17.1. The BRIEF Format
  370. 4.17.2. The FTP Format
  371. 4.18. Unprefixing NUL
  372. 4.19. Clear-Channel Protocol
  373. 4.20. Streaming Protocol
  374. 4.20.1. Commands for Streaming
  375. 4.20.2. Examples of Streaming
  376. 4.20.2.1. Streaming on Socket-to-Socket Connections
  377. 4.20.2.2. Streaming on Telnet Connections
  378. 4.20.2.3. Streaming with Limited Packet Length
  379. 4.20.2.4. Streaming on Dialup Connections
  380. 4.20.2.5. Streaming on X.25 Connections
  381. 4.20.3. Streaming - Preliminary Conclusions
  382. 4.21. The TRANSMIT Command
  383. 4.22. Coping with Faulty Kermit Implementations
  384. 4.22.1. Failure to Accept Modern Negotiation Strings
  385. 4.22.2. Failure to Negotiate 8th-bit Prefixing
  386. 4.22.3. Corrupt Files
  387. 4.22.4. Spurious Cancellations
  388. 4.22.5. Spurious Refusals
  389. 4.22.6. Failures during the Data Transfer Phase
  390. 4.22.7. Fractured Filenames
  391. 4.22.8. Bad File Dates
  392. 4.23. File Transfer Recovery
  393. 4.24. FILE COLLISION UPDATE Clarification
  394. 4.25. Autodownload Improvements
  395. (5) CLIENT / SERVER
  396. 5.0. Hints
  397. 5.1. New Command-Line Options
  398. 5.2. New Client Commands
  399. 5.3. New Server Capabilities
  400. 5.3.1. Creating and Removing Directories
  401. 5.3.2. Directory Listings
  402. 5.4. Syntax for Remote Filenames with Embedded Spaces
  403. 5.5. Automatic Orientation Messages upon Directory Change
  404. 5.6. New Server Controls
  405. 5.7. Timeouts during REMOTE HOST Command Execution
  406. (6) INTERNATIONAL CHARACTER SETS
  407. 6.0. ISO 8859-15 Latin Alphabet 9
  408. 6.1. The HP-Roman8 Character Set
  409. 6.2. Greek Character Sets
  410. 6.3. Additional Latin-2 Character Sets
  411. 6.4. Additional Cyrillic Character Sets
  412. 6.5. Automatic Character-Set Switching
  413. 6.6. Unicode
  414. 6.6.1. Overview of Unicode
  415. 6.6.2. UCS Byte Order
  416. 6.6.2. UCS Transformation Formats
  417. 6.6.3. Conformance Levels
  418. 6.6.4. Relationship of Unicode with Kermit's Other Character Sets
  419. 6.6.5. Kermit's Unicode Features
  420. 6.6.5.1. File Transfer
  421. 6.6.5.2. The TRANSLATE Command
  422. 6.6.5.3. Terminal Connection
  423. 6.6.5.4. The TRANSMIT Command
  424. 6.6.5.5. Summary of Kermit Unicode Commands
  425. 6.7. Client / Server Character-Set Switching
  426. (7) SCRIPT PROGRAMMING
  427. 7.0. Bug Fixes
  428. 7.1. The INPUT Command
  429. 7.1.1. INPUT Timeouts
  430. 7.1.2. New INPUT Controls
  431. 7.1.3. INPUT with Pattern Matching
  432. 7.1.4. The INPUT Match Result
  433. 7.2. New or Improved Built-In Variables
  434. 7.3. New or Improved Built-In Functions
  435. 7.4. New IF Conditions
  436. 7.5. Using More than Ten Macro Arguments
  437. 7.6. Clarification of Function Call Syntax
  438. 7.7. Autodownload during INPUT Command Execution
  439. 7.8. Built-in Help for Functions.
  440. 7.9. Variable Assignments
  441. 7.9.1. Assignment Operators
  442. 7.9.2. New Assignment Commands
  443. 7.10. Arrays
  444. 7.10.1. Array Initializers
  445. 7.10.2. Turning a String into an Array of Words
  446. 7.10.3. Arrays of Filenames
  447. 7.10.4. Automatic Arrays
  448. 7.10.5. Sorting Arrays
  449. 7.10.6. Displaying Arrays
  450. 7.10.7. Other Array Operations
  451. 7.10.8. Hints for Using Arrays
  452. 7.10.9. Do-It-Yourself Arrays
  453. 7.10.10. Associative Arrays
  454. 7.11. OUTPUT Command Improvements
  455. 7.12. Function and Variable Diagnostics
  456. 7.13. Return Value of Macros
  457. 7.14. The ASSERT, FAIL, and SUCCEED Commands.
  458. 7.15. Using Alarms
  459. 7.16. Passing Arguments to Command Files
  460. 7.17. Dialogs with Timed Responses
  461. 7.18. Increased Flexibility of SWITCH Case Labels
  462. 7.19. "Kerbang" Scripts
  463. 7.20. IF and XIF Statement Syntax
  464. 7.20.1. The IF/XIF Distinction
  465. 7.20.2. Boolean Expressions (The IF/WHILE Condition)
  466. 7.21. Screen Formatting and Cursor Control
  467. 7.22. Evaluating Arithmetic Expressions
  468. 7.23. Floating-Point Arithmetic
  469. 7.24. Tracing Script Execution
  470. 7.25. Compact Substring Notation
  471. 7.26. New WAIT Command Options
  472. 7.26.1. Waiting for Modem Signals
  473. 7.26.2. Waiting for File Events
  474. 7.27. Relaxed FOR and SWITCH Syntax
  475. (8) USING OTHER FILE TRANSFER PROTOCOLS
  476. (9) COMMAND-LINE OPTIONS
  477. 9.0. Extended-Format Command-Line Options
  478. 9.1. Command Line Personalities
  479. 9.2. Built-in Help for Command Line Options
  480. 9.3. New Command-Line Options
  481. (10) C-KERMIT AND G-KERMIT
  482. III. APPENDICES
  483. III.1. Character Set Tables
  484. III.1.1. The Hewlett Packard Roman8 Character Set
  485. III.1.2. Greek Character Sets
  486. III.1.2.1. The ISO 8859-7 Latin / Greek Alphabet
  487. III.1.2.2. The ELOT 927 Character Set
  488. III.1.2.3. PC Code Page 869
  489. III.2. Updated Country Codes
  490. IV. ERRATA & CORRIGENDA: Corrections to "Using C-Kermit" 2nd Edition.
  491. V. ADDITIONAL COPYRIGHT NOTICES
  492. I. C-KERMIT DOCUMENTATION
  493. The user manual for C-Kermit is:
  494. Frank da Cruz and Christine M. Gianone, Using C-Kermit, Second
  495. Edition, Digital Press / Butterworth-Heinemann, Woburn, MA, 1997,
  496. 622 pages, ISBN 1-55558-164-1.
  497. The present document is a supplement to Using C-Kermit 2nd Ed, not a
  498. replacement for it.
  499. US single-copy price: $52.95; quantity discounts available. Available
  500. in bookstores or directly from Columbia University:
  501. The Kermit Project
  502. Columbia University
  503. 612 West 115th Street
  504. New York NY 10025-7799
  505. USA
  506. Telephone: +1 (212) 854-3703
  507. Fax: +1 (212) 662-6442
  508. Domestic and overseas orders accepted. Price: US $44.95 (US, Canada,
  509. and Mexico). Shipping: $4.00 within the USA; $15.00 to all other
  510. countries. Orders may be paid by MasterCard or Visa, or prepaid by
  511. check in US dollars. Add $65 bank fee for checks not drawn on a US
  512. bank. Do not include sales tax. Inquire about quantity discounts.
  513. You can also order by phone from the publisher, Digital Press /
  514. Butterworth-Heinemann, with MasterCard, Visa, or American Express:
  515. +1 800 366-2665 (Woburn, Massachusetts office for USA & Canada)
  516. +44 1865 314627 (Oxford, England distribution centre for UK & Europe)
  517. +61 03 9245 7111 (Melbourne, Vic, office for Australia & NZ)
  518. +65 356-1968 (Singapore office for Asia)
  519. +27 (31) 2683111 (Durban office for South Africa)
  520. AGerman-language edition of the First Edition is also available:
  521. Frank da Cruz and Christine M. Gianone, C-Kermit - Einführung und
  522. Referenz, Verlag Heinz Heise, Hannover, Germany (1994). ISBN
  523. 3-88229-023-4. Deutsch von Gisbert W. Selke. Price: DM 88,00. Verlag
  524. Heinz Heise GmbH & Co. KG, Helstorfer Strasse 7, D-30625 Hannover.
  525. Tel. +49 (05 11) 53 52-0, Fax. +49 (05 11) 53 52-1 29.
  526. TheKermit file transfer protocol is specified in:
  527. Frank da Cruz, Kermit, A File Transfer Protocol, Digital Press,
  528. Bedford, MA, 1987, 379 pages, ISBN 0-932376-88-6. US single-copy
  529. price: $39.95. Availability as above.
  530. News and articles about Kermit software and protocol are published
  531. periodically in the journal,Kermit News. Subscriptions are free;
  532. contact Columbia University at the address above.
  533. Online news about Kermit is published in the
  534. comp.protocols.kermit.announce andcomp.protocols.kermit.misc
  535. newsgroups.
  536. II. NEW FEATURES
  537. Support for the Bell Labs Plan 9 operating system was added to version
  538. 6.0 too late to be mentioned in the book (although it does appear on
  539. the cover).
  540. Specific changes and additions are grouped together by major topic,
  541. roughly corresponding to the chapters ofUsing C-Kermit.
  542. 0. INCOMPATIBILITIES WITH PREVIOUS RELEASES
  543. 1. C-Kermit 7.0 uses FAST Kermit protocol settings by default. This
  544. includes "unprefixing" of certain control characters. Because of
  545. this, file transfers that worked with previous releases might not
  546. work in the new release (but it is more likely that they will work,
  547. and much faster). If a transfer fails, you'll get a
  548. context-sensitive hint suggesting possible causes and cures.
  549. Usually SET PREFIXING ALL does the trick.
  550. 2. C-Kermit 7.0 transfers files in BINARY mode by default. To restore
  551. the previous behavior, put SET FILE TYPE TEXT in your C-Kermit
  552. initialization file.
  553. 3. No matter whether FILE TYPE is BINARY or TEXT by default, C-Kermit
  554. 7.0 now switches between text and binary mode automatically on a
  555. per-file basis according to various criteria, including (a) which
  556. kind of platform is on the other end of the connection (if known),
  557. (b) the version of Kermit on the other end, and (c) the file's name
  558. (see Section 4, especially 4.3). To disable this
  559. automatic switching and restore the earlier behavior, put SET
  560. TRANSFER MODE MANUAL in your C-Kermit initialization file. To
  561. disable automatic switching for a particular transfer, include a
  562. /TEXT or /BINARY switch with your SEND or GET command.
  563. 4. The RESEND and REGET commands automatically switch to binary mode;
  564. previously if RESEND or REGET were attempted when FILE TYPE was
  565. TEXT, these commands would fail immediately, with a message telling
  566. you they work only when the FILE TYPE is BINARY. Now they simply do
  567. this for you. See Section 4.23 for additional (important)
  568. information.
  569. 5. SET PREFIXING CAUTIOUS and MINIMAL now both prefix linefeed (10 and
  570. 138) in case rlogin, ssh, or cu are "in the middle", since
  571. otherwise <LF>~ might appear in Kermit packets, and this would
  572. cause rlogin, ssh, or cu to disconnect, suspend, escape back, or
  573. otherwise wreck the file transfer. Xon and Xoff are now always
  574. prefixed too, even when Xon/Xoff flow control is not in effect,
  575. since unprefixing them has proven dangerous on TCP/IP connections.
  576. 6. In UNIX, VMS, Windows, and OS/2, the DIRECTORY command is built
  577. into C-Kermit itself rather than implemented by running an external
  578. command or program. The built-in command might not behave the way
  579. the platform-specific external one did, but many options are
  580. available for customization. Of course the underlying
  581. platform-specific command can still be accessed with "!", "@", or
  582. "RUN" wherever the installation does not forbid. In UNIX, the "ls"
  583. command can be accessed directly as "ls" in C-Kermit. See
  584. Section 4.5.1 for details.
  585. 7. SEND ? prints a list of switches rather than a list of filenames.
  586. If you want to see a list of filenames, use a (system-dependent)
  587. construction such as SEND ./? (for UNIX, Windows, or OS/2), SEND
  588. []? (VMS), etc. See Sections 1.5 and4.7.1.
  589. 8. In UNIX, OS-9, and Kermit 95, the wildcard characters in previous
  590. versions were * and ?. In C-Kermit 7.0 they are *, ?, [, ], {, and
  591. }, with dash used inside []'s to denote ranges and comma used
  592. inside {} to separate list elements. If you need to include any of
  593. these characters literally in a filename, precede each one with
  594. backslash (\). See Section 4.9.
  595. 9. SET QUIET { ON, OFF } is now on the command stack, just like SET
  596. INPUT CASE, SET COUNT, SET MACRO ERROR, etc, as described on p.458
  597. ofUsing C-Kermit, 2nd Edition. This allows any macro or
  598. command file to SET QUIET ON or OFF without worrying about saving
  599. and restoring the global QUIET value. For example, this lets you
  600. write a script that tries SET LINE on lots of devices until it
  601. finds one free without spewing out loads of error messages, and
  602. also without disturbing the global QUIET setting, whatever it was.
  603. 10. Because of the new "." operator (which introduces assignments),
  604. macros whose names begin with "." can not be invoked "by name".
  605. However, they still can be invoked with DO.
  606. 11. The syntax of the EVALUATE command has changed. SeeSection
  607. 7.9.2. To restore the previous syntax, use SET EVALUATE OLD.
  608. 12. The \v(directory) variable now includes the trailing directory
  609. separator; in previous releases it did not. This is to allow
  610. constructions such as:
  611. cd \v(dir)data.tmp
  612. to work across platforms that might have different directory
  613. notation, such as UNIX, Windows, and VMS.
  614. 13. Prior to C-Kermit 7.0, the FLOW-CONTROL setting was global and
  615. sticky. In C-Kermit 7.0, there is an array of default flow-control
  616. values for each kind of connection, that are applied automatically
  617. at SET LINE/PORT/HOST time. Thus a SET FLOW command given before
  618. SET LINE/PORT/HOST is likely to be undone. Therefore SET FLOW can
  619. be guaranteed to have the desired effect only if given after the
  620. SET LINE/PORT/HOST command.
  621. 14. Character-set translation works differently in the TRANSMIT command
  622. when (a) the file character-set is not the same as the local end of
  623. the terminal character-set, or (b) when the terminal character-set
  624. is TRANSPARENT.
  625. 1. PROGRAM AND FILE MANAGEMENT AND COMMANDS
  626. 1.0. Bug Fixes
  627. The following patches were issued to correct bugs in C-Kermit 6.0.
  628. These are described in detail in the 6.0 PATCHES file. All of these
  629. fixes have been incorporated in C-Kermit 6.1 (never released except as
  630. K95 1.1.16-17) and 7.0.
  631. 0001 All UNIX C-Kermit mishandles timestamps on files before 1970
  632. 0002 Solaris 2.5++ Compilation error on Solaris 2.5 with Pro C
  633. 0003 All VMS CKERMIT.INI Fix for VMS
  634. 0004 VMS/VAX/UCX 2.0 C-Kermit 6.0 can't TELNET on VAX/VMS with UCX 2.0
  635. 0005 All C-Kermit Might Send Packets Outside Window
  636. 0006 All MOVE from SEND-LIST does not delete original files
  637. 0007 Solaris 2.5++ Higher serial speeds on Solaris 2.5
  638. 0008 All C-Kermit application file name can't contain spaces
  639. 0009 AT&T 7300 UNIXPC setuid and hardware flow-control problems
  640. 0010 Linux on Alpha Patch to make ckutio.c compile on Linux/Alpha
  641. 0011 OS-9/68000 2.4 Patch to make ck9con.c compile on OS-9/68000 2.4
  642. 0012 MW Coherent 4.2 Patches for successful build on Coherent 4.2
  643. 0013 SINIX-Y 5.43 "delay" variable conflicts with <sys/clock.h>
  644. 0014 VMS/VAX/CMU-IP Subject: Patches for VAX/VMS 5.x + CMU-IP
  645. 0015 All XECHO doesn't flush its output
  646. 0016 VMS CD and other directory operations might not work
  647. 0017 Linux 1.2.x++ Use standard POSIX interface for high serial speeds
  648. 0018 UNIX SET WILDCARD-EXPANSION SHELL dumps core
  649. 0019 All Hayes V.34 modem init string problem
  650. 0020 All READ command does not fail if file not open
  651. 0021 All Problems with long function arguments
  652. 0022 All Certain \function()s can misbehave
  653. 0023 All X MOD 0 crashes program
  654. 0024 All Internal bulletproofing for lower() function
  655. 0025 OpenBSD Real OpenBSD support for C-Kermit 6.0
  656. 0026 All Incorrect checks for macro/command-file nesting depth
  657. 0027 All ANSWER doesn't automatically CONNECT
  658. 0028 All Overzealous EXIT warning
  659. 0029 All OUTPUT doesn't echo when DUPLEX is HALF
  660. 0030 All Minor problems with REMOTE DIRECTORY/DELETE/etc
  661. 0031 All CHECK command broken
  662. 0032 All Problem with SET TRANSMIT ECHO
  663. 0033 UNIX, VMS, etc HELP SET SERVER says too much
  664. 0034 All READ and !READ too picky about line terminators
  665. 0035 All END from inside SWITCH doesn't work
  666. 0036 All Problem telnetting to multihomed hosts
  667. 0037 All Redirection failures in REMOTE xxx > file
  668. REDIRECT was missing in many UNIX C-Kermit implementations; in version
  669. 7.0, it should be available in all of them.
  670. 1.1. Command Continuation
  671. Comments that start with ";" or "#" can no longer be continued. In:
  672. ; this is a comment -
  673. echo blah
  674. the ECHO command will execute, rather than being taken as a
  675. continuation of the preceding comment line. This allows easy
  676. "commenting out" of commands from macro definitions.
  677. However, the text of the COMMENT command can still be continued onto
  678. subsequent lines:
  679. comment this is a comment -
  680. echo blah
  681. As of version 6.0, backslash is no longer a valid continuation
  682. character. Only hyphen should be used for command continuation. This is
  683. to make it possible to issue commands like "cd a:\" on DOS-like
  684. systems.
  685. As of version 7.0:
  686. * You can quote a final dash to prevent it from being a continuation
  687. character:
  688. echo foo\-
  689. This prints "foo-". The command is not continued.
  690. * You can enter commands such as:
  691. echo foo - ; this is a comment
  692. interactively and they are properly treated as continued commands.
  693. Previously this worked only in command files.
  694. 1.2. Editor Interface
  695. SET EDITOR name [ options ]
  696. Lets you specify a text-editing program. The name can be a fully
  697. specified pathname like /usr/local/bin/emacs19/emacs, or it can
  698. be the name of any program in your PATH, e.g. "set editor
  699. emacs". In VMS, it must be a DCL command like "edit",
  700. "edit/tpu", "emacs", etc. If an environment variable EDITOR is
  701. defined when Kermit starts, its value is the default editor. You
  702. can also specify options to be included on the editor command
  703. line. Returns to Kermit when the editor exits.
  704. EDIT [ filename ]
  705. If the EDIT command is given without a filename, then if a
  706. previous filename had been given to an EDIT command, it is used;
  707. if not, the editor is started without a file. If a filename is
  708. given, the editor is started on that file, and the filename is
  709. remembered for subsequent EDIT commands.
  710. SHOW EDITOR
  711. Displays the full pathname of your text editor, if any, along
  712. with any command line options, and the file most recently edited
  713. (and therefore the default filename for your next EDIT command).
  714. Related variables: \v(editor), \v(editopts), \v(editfile).
  715. 1.3. Web Browser and FTP Interface
  716. C-Kermit includes an FTP command, which simply runs the FTP program;
  717. C-Kermit does not include any built-in support for Internet File
  718. Transfer Protocol, nor any method for interacting directly with an FTP
  719. server. In version 7.0, however, C-Kermit lets you specify your FTP
  720. client:
  721. SET FTP-CLIENT [ name [ options ] ]
  722. The name is the name of the FTP executable. In UNIX, Windows, or
  723. OS/2, it can be the filename of any executable program in your
  724. PATH (e.g. "ftp.exe" in Windows, "ftp" in UNIX); elsewhere (or
  725. if you do not have a PATH definition), it must be the fully
  726. specified pathname of the FTP program. If the name contains any
  727. spaces, enclose it braces. Include any options after the
  728. filename; these depend the particular ftp client.
  729. The Web browser interface is covered in the following subsections.
  730. 1.3.1. Invoking your Browser from C-Kermit
  731. BROWSE [ url ]
  732. Starts your preferred Web browser on the URL, if one is given,
  733. otherwise on the most recently given URL, if any. Returns to
  734. Kermit when the browser exits.
  735. SET BROWSER [ name [ options ] ]
  736. Use this command to specify the name of your Web browser
  737. program, for example: "set browser lynx". The name must be in
  738. your PATH, or else it must be a fully specified filename; in VMS
  739. it must be a DCL command.
  740. SHOW BROWSER
  741. Displays the current browser, options, and most recent URL.
  742. Related variables: \v(browser), \v(browsopts), \v(browsurl).
  743. Also see Section 2.15: Contacting Web Servers with the HTTP
  744. Command.
  745. 1.3.2. Invoking C-Kermit from your Browser
  746. The method for doing this depends, of course, on your browser. Here are
  747. some examples:
  748. Netscape on UNIX (X-based)
  749. In the Options->Applications section, set your Telnet
  750. application to:
  751. xterm -e /usr/local/bin/kermit/kermit -J %h %p
  752. (replace "/usr/local/bin/kermit/kermit" by C-Kermit's actual
  753. pathname). -J is C-Kermit's command-line option to "be like
  754. Telnet"; %h and %p are Netscape placeholders for hostname and
  755. port.
  756. Lynx on UNIX
  757. As far as we know, this can be done only at compile time. Add
  758. the following line to the Lynx userdefs.h file before building
  759. the Lynx binary:
  760. #define TELNET_COMMAND "/opt/bin/kermit -J"
  761. And then add lines like the following to the Lynx.cfg file:
  762. DOWNLOADER:Kermit binary download:/opt/bin/kermit -i -V -s %s -a %s:TRUE
  763. DOWNLOADER:Kermit text download:/opt/bin/kermit -s %s -a %s:TRUE
  764. UPLOADER:Kermit binary upload:/opt/bin/kermit -i -r -a %s:TRUE
  765. UPLOADER:Kermit text upload:/opt/bin/kermit -r -a %s:TRUE
  766. UPLOADER:Kermit text get:/opt/bin/kermit -g %s:TRUE
  767. UPLOADER:Kermit binary get:/opt/bin/kermit -ig %s:TRUE
  768. But none of the above is necessary if you make C-Kermit your default
  769. Telnet client, which you can do by making a symlink called 'telnet' to
  770. the C-Kermit 7.0 binary. See Section 9.1 for details.
  771. 1.4. Command Editing
  772. Ctrl-W ("Word delete") was changed in 7.0 to delete back to the
  773. previous non-alphanumeric, rather than all the way back to the previous
  774. space.
  775. 1.5. Command Switches
  776. As of version 7.0, C-Kermit's command parser supports a new type of
  777. field, called a "switch". This is an optional command modifier.
  778. 1.5.1. General Switch Syntax
  779. A switch is a keyword beginning with a slash (/). If it takes a value,
  780. then the value is appended to it (with no intervening spaces),
  781. separated by a colon (:) or equal sign (=). Depending on the switch,
  782. the value may be a number, a keyword, a filename, a date/time, etc.
  783. Examples:
  784. send oofa.txt ; No switches
  785. send /binary oofa.zip ; A switch without a value
  786. send /protocol:zmodem oofa.zip ; A switch with a value (:)
  787. send /protocol=zmodem oofa.zip ; A switch with a value (=)
  788. send /text /delete /as-name:x.x oofa.txt ; Several switches
  789. Like other command fields, switches are separated from other fields,
  790. and from each other, by whitespace, as shown in the examples just
  791. above. You can not put them together like so:
  792. send/text/delete/as-name:x.x oofa.txt
  793. (as you might do in VMS or DOS, or as we might once have done in
  794. TOPS-10 or TOPS0-20, or PIP). This is primarily due to ambiguity
  795. between "/" as switch introducer versus "/" as UNIX directory
  796. separator; e.g. in:
  797. send /delete/as-name:foo/text oofa.txt
  798. Does "foo/text" mean the filename is "foo" and the transfer is to be in
  799. text mode, or does it mean the filename is "foo/text"? Therefore we
  800. require whitespace between switches to resolve the ambiguity. (That's
  801. only one of several possible ambiguities -- it is also conceivable that
  802. a file called "text" exists in the path "/delete/as-name:foo/").
  803. In general, if a switch can take a value, but you omit it, then either
  804. a reasonable default value is supplied, or an error message is printed:
  805. send /print:-Plaserwriter oofa.txt ; Value included = print options
  806. send /print oofa.txt ; Value omitted, OK
  807. send /mail:kermit@columbia.edu oofa.txt ; Value included = address
  808. send /mail oofa.txt ; Not OK - address required
  809. ?Address required
  810. Context-sensitive help (?) and completion (Esc or Tab) are available in
  811. the normal manner:
  812. C-Kermit> send /pr? Switch, one of the following:
  813. /print /protocol
  814. C-Kermit> send /pro<ESC>tocol:? File-transfer protocol,
  815. one of the following:
  816. kermit xmodem ymodem ymodem-g zmodem
  817. C-Kermit> send /protocol:k<TAB>ermit
  818. If a switch takes a value and you use completion on it, a colon (:) is
  819. printed at the end of its name to indicate this. If it does not take a
  820. value, a space is printed.
  821. Also, if you type ? in a switch field, switches that take values are
  822. shown with a trailing colon; those that don't take values are shown
  823. without one.
  824. 1.5.2. Order and Effect of Switches
  825. The order of switches should not matter, except that they are evaluated
  826. from left to right, so if you give two switches with opposite effects,
  827. the rightmost one is used:
  828. send /text /binary oofa.zip ; Sends oofa.zip in binary mode.
  829. Like other command fields, switches have no effect whatsoever until the
  830. command is entered (by pressing the Return or Enter key). Even then,
  831. switches affect only the command with which they are included; they do
  832. not have global effect or side effects.
  833. 1.5.3. Distinguishing Switches from Other Fields
  834. All switches are optional. A command that uses switches lets you give
  835. any number of them, including none at all. Example:
  836. send /binary oofa.zip
  837. send /bin /delete oofa.zip
  838. send /bin /as-name:mupeen.zip oofa.zip
  839. send oofa.zip
  840. But how does Kermit know when the first "non-switch" is given? It has
  841. been told to look for both a switch and for something else, the data
  842. type of the next field (filename, number, etc). In most cases, this
  843. works well. But conflicts are not impossible. Suppose, for example, in
  844. UNIX there was a file named "text" in the top-level directory. The
  845. command to send it would be:
  846. send /text
  847. But C-Kermit would think this was the "/text" switch. To resolve the
  848. conflict, use braces:
  849. send {/text}
  850. or other circumlocutions such as "send //text", "send /./text", etc.
  851. The opposite problem can occur if you give an illegal switch that
  852. happens to match a directory name. For example:
  853. send /f oofa.txt
  854. There is no "/f" switch (there are several switches that begin with
  855. "/f", so "/f" is ambiguous). Now suppose there is an "f" directory in
  856. the root directory; then this command would be interpreted as:
  857. Send all the files in the "/f" directory, giving each one an as-name
  858. of "oofa.txt".
  859. This could be a mistake, or it could be exactly what you intended;
  860. C-Kermit has no way of telling the difference. To avoid situations like
  861. this, spell switches out in full until you are comfortable enough with
  862. them to know the minimum abbreviation for each one. Hint: use ? and
  863. completion while typing switches to obtain the necessary feedback.
  864. 1.5.4. Standard File Selection Switches
  865. The following switches are used on different file-oriented commands
  866. (such as SEND, DIRECTORY, DELETE, PURGE) to refine the selection of
  867. files that match the given specification.
  868. /AFTER:date-time
  869. Select only those files having a date-time later than the one
  870. given. See Section 1.6 for date-time formats. Synonym:
  871. /SINCE.
  872. /NOT-AFTER:date-time
  873. Select only those files having a date-time not later than (i.e.
  874. earlier or equal to) the one given. Synonym: /NOT-SINCE.
  875. /BEFORE:date-time
  876. Select only those files having a date-time earlier than the one
  877. given.
  878. /NOT-BEFORE:date-time
  879. Select only those files having a date-time not earlier than
  880. (i.e. later or equal to) the one given.
  881. /DOTFILES
  882. UNIX and OS-9 only: The filespec is allowed to match files whose
  883. names start with (dot) period. Normally these files are not
  884. shown.
  885. /NODOTFILES
  886. (UNIX and OS-9 only) Don't show files whose names start with dot
  887. (period). This is the opposite of /DOTFILES, and is the default.
  888. Note that when a directory name starts with a period, the
  889. directory and (in recursive operations) all its subdirectories
  890. are skipped.
  891. /LARGER-THAN:number
  892. Only select files larger than the given number of bytes.
  893. /SMALLER-THAN:number
  894. Only select files smaller than the given number of bytes.
  895. /EXCEPT:pattern
  896. Specifies that any files whose names match the pattern, which
  897. can be a regular filename, or may contain "*" and/or "?"
  898. metacharacters (wildcards), are not to be selected. Example:
  899. send /except:*.log *.*
  900. sends all files in the current directory except those with a
  901. filetype of ".log". Another:
  902. send /except:*.~*~ *.*
  903. sends all files except the ones that look like Kermit or EMACS
  904. backup files (such as "oofa.txt.~17~") (of course you can also
  905. use the /NOBACKUP switch for this).
  906. The pattern matcher is the same one used by IF MATCH string
  907. pattern ( Section 7.4), so you can test your patterns using
  908. IF MATCH. If you need to match a literal * or ? (etc), precede
  909. it by a backslash (\). If the pattern contains any spaces, it
  910. must be enclosed in braces:
  911. send /except:{Foo bar} *.*
  912. The pattern can also be a list of up to 8 patterns. In this
  913. case, the entire pattern must be enclosed in braces, and each
  914. sub-pattern must also be enclosed in braces; this eliminates the
  915. need for designating a separator character, which is likely to
  916. also be a legal filename character on some platform or other,
  917. and therefore a source of confusion. You may include spaces
  918. between the subpatterns but they are not necessary. The
  919. following two commands are equivalent:
  920. send /except:{{ck*.o} {ck*.c}} ck*.?
  921. send /except:{{ck*.o}{ck*.c}} ck*.?
  922. If a pattern is to include a literal brace character, precede it
  923. with "\". Also note the apparent conflict of this list format
  924. and the string-list format described in Section 4.9.1. In
  925. case you want to include a wildcard string-list with braces on
  926. its outer ends as an /EXCEPT: argument, do it like this:
  927. send /except:{{{ckuusr.c,ckuus2.c,ckuus6.c}}} ckuus*.c
  928. 1.5.5. Setting Preferences for Different Commands
  929. Certain oft-used commands offer lots of switches because different
  930. people have different requirements or preferences. For example, some
  931. people want to be able to delete files without having to watch a list
  932. of the deleted files scroll past, while others want to be prompted for
  933. permission to delete each file. Different people prefer different
  934. directory-listing styles. And so on. Such commands can be tailored with
  935. the SET OPTIONS command:
  936. SET OPTIONS command [ switch [ switch [ ... ] ] ]
  937. Sets each switch as the default for the given command, replacing
  938. the "factory default". Of course you can also override any
  939. defaults established by the SET OPTIONS command by including the
  940. relevant switches in the affected command any time you issue it.
  941. SHOW OPTIONS
  942. Lists the commands that allows option-setting, and the options
  943. currently in effect, if any, for each. Switches that have
  944. synonyms are shown under their primary name; for example. /LOG
  945. and /VERBOSE are shown as /LIST.
  946. Commands for which options may be set include DIRECTORY, DELETE, PURGE,
  947. and TYPE. Examples:
  948. SET OPTIONS DIRECTORY /PAGE /NOBACKUP /HEADING /SORT:DATE /REVERSE
  949. SET OPTIONS DELETE /LIST /NOHEADING /NOPAGE /NOASK /NODOTFILES
  950. SET OPTIONS TYPE /PAGE
  951. Not necessarily all of a command's switches can be set as options. For
  952. example, file selection switches, since these would normally be
  953. different for each command.
  954. Put the desired SET OPTIONS commands in your C-Kermit customization
  955. file for each command whose default switches you want to change every
  956. time you run C-Kermit.
  957. 1.6. Dates and Times
  958. Some commands and switches take date-time values, such as:
  959. send /after:{8-Feb-2000 10:28:01}
  960. Various date-time formats are acceptable. The rules for the date are:
  961. * The year must have 4 digits.
  962. * If the year comes first, the second field is the month.
  963. * The day, month, and year may be separated by spaces, /, -, or
  964. underscore.
  965. * The month may be numeric (1 = January) or spelled out or
  966. abbreviated in English.
  967. If the date-time string contains any spaces, it must be enclosed in
  968. braces. Examples of legal dates:
  969. Interpretation:
  970. 2000-Feb-8 8 February 2000
  971. {2000 Feb 8} 8 February 2000
  972. 2000/Feb/8 8 February 2000
  973. 2000_Feb_8 8 February 2000
  974. 2000-2-8 8 February 2000
  975. 2000-02-08 8 February 2000
  976. 8-Feb-2000 8 February 2000
  977. 08-Feb-2000 8 February 2000
  978. 12/25/2000 25 December 2000
  979. 25/12/2000 25 December 2000
  980. The last two examples show that when the year comes last, and the month
  981. is given numerically, the order of the day and month doesn't matter as
  982. long as the day is 13 or greater (mm/dd/yyyy is commonly used in the
  983. USA, whereas dd/mm/yyyy is the norm in Europe). However:
  984. 08/02/2000 Is ambiguous and therefore not accepted.
  985. If a date is given, the time is optional and defaults to 00:00:00. If
  986. the time is given with a date, it must follow the date, separated by
  987. space, /, -, or underscore, and with hours, minutes, and seconds
  988. separated by colon (:). Example:
  989. 2000-Feb-8 10:28:01 Represents 8 February 2000, 10:28:01am
  990. If a date is not given, the current date is used and a time is
  991. required.
  992. Time format is hh:mm:ss or hh:mm or hh in 24-hour format, or followed
  993. by "am" or "pm" (or "AM" or "PM") to indicate morning or afternoon.
  994. Examples of times that are acceptable:
  995. Interpretation:
  996. 3:23:56 3:23:56am
  997. 3:23:56am 3:23:56am
  998. 3:23:56pm 3:23:56pm = 15:23:56
  999. 15:23:56 3:23:56pm = 15:23:56
  1000. 3:23pm 3:23:00pm = 15:23:00
  1001. 3:23PM 3:23:00pm = 15:23:00
  1002. 3pm 3:00:00pm = 15:00:00
  1003. Examples of legal date-times:
  1004. send /after:{8 Feb 2000 10:28:01}
  1005. send /after:8_Feb_2000_10:28:01
  1006. send /after:8-Feb-2000/10:28:01
  1007. send /after:2000/02/08/10:28:01
  1008. send /after:2000/02/08_10:28:01
  1009. send /after:2000/02/08_10:28:01am
  1010. send /after:2000/02/08_10:28:01pm
  1011. send /after:2000/02/08_10:28pm
  1012. send /after:2000/02/08_10pm
  1013. send /after:10:00:00pm
  1014. send /after:10:00pm
  1015. send /after:10pm
  1016. send /after:22
  1017. Finally, there is a special all-numeric format you can use:
  1018. yyyymmdd hh:mm:ss
  1019. For example:
  1020. 20000208 10:28:01
  1021. This is Kermit's standard date-time format (based on ISO 8601), and is
  1022. accepted (among other formats) by any command or switch that requires a
  1023. date-time, and is output by any function whose result is a calendar
  1024. date-time.
  1025. There are no optional parts to this format and it must be exactly 17
  1026. characters long, punctuated as shown (except you can substitute
  1027. underscore for space in contexts where a single "word" is required).
  1028. The time is in 24-hour format (23:00:00 is 11:00pm). This is the format
  1029. returned by \fdate(filename), so you can also use constructions like
  1030. this:
  1031. send /after:\fdate(oofa.txt)
  1032. which means "all files newer than oofa.txt".
  1033. Besides explicit dates, you can also use the any of the following
  1034. shortcuts:
  1035. TODAY
  1036. Stands for the current date at 00:00:00.
  1037. TODAY 12:34:56
  1038. Stands for the current date at the given time.
  1039. YESTERDAY
  1040. Stands for yesterday's date at 00:00:00. A time may also be
  1041. given.
  1042. TOMORROW
  1043. Stands for tomorrow's date at 00:00:00. A time may also be
  1044. given.
  1045. + number { DAYS, WEEKS, MONTHS, YEARS } [ time ]
  1046. Is replaced by the future date indicated, relative to the
  1047. current date. If the time is omitted, 00:00:00 is used.
  1048. Examples: +3days, +2weeks, +1year, +37months.
  1049. - number { DAYS, WEEKS, MONTHS, YEARS } [ time ]
  1050. Is replaced by the past date indicated, relative to the current
  1051. date. If the time is omitted, 00:00:00 is used.
  1052. The time can be separated from the date shortcut by any of the same
  1053. separators that are allowed for explicit date-times: space, hyphen,
  1054. slash, period, or underscore. In switches and other space-delimited
  1055. fields, use non-spaces to separate date/time fields, or enclose the
  1056. date-time in braces, e.g.:
  1057. purge /before:-4days_12:00:00
  1058. purge /before:{- 4 days 12:00:00}
  1059. Of course you can also use variables:
  1060. define \%n 43
  1061. purge /before:-\%ndays_12:00:00
  1062. Shortcut names can be abbreviated to any length that still
  1063. distinguishes them from any other name that can appear in the same
  1064. context, e.g. "TOD" for today, "Y" for yesterday. Also, the special
  1065. abbreviation "wks" is accepted for WEEKS, and "yrs" for "YEARS".
  1066. (To see how to specify dates relative to a specific date, rather than
  1067. the current one, see the\fmjd() function description below.)
  1068. You can check date formats with the DATE command. DATE by itself prints
  1069. the current date and time in standard format: yyyymmdd hh:mm:ss. DATE
  1070. followed by a date and/or time (including shortcuts) converts it to
  1071. standard format if it can understand it, otherwise it prints an error
  1072. message.
  1073. The following variables and functions deal with dates and times; any
  1074. function argument designated as "date-time" can be in any of the
  1075. formats described above.
  1076. \v(day)
  1077. The first three letters of the English word for the current day
  1078. of the week, e.g. "Wed".
  1079. \fday(date-time)
  1080. The first three letters of the English word for day of the week
  1081. of the given date. If a time is included, it is ignored.
  1082. Example: \fday(8 Feb 1988) = "Mon".
  1083. \v(nday)
  1084. The numeric day of the week: 0 = Sunday, 1 = Monday, ..., 6 =
  1085. Saturday.
  1086. \fnday(date-time)
  1087. The numeric day of the week for the given date. If a time is
  1088. included, it is ignored. Example: \fnday(8 Feb 1988) = "1".
  1089. \v(date)
  1090. The current date as dd mmm yyyy, e.g. "08 Feb 2000" (as in this
  1091. example, a leading zero is supplied for day-of-month less than
  1092. 10).
  1093. \v(ndate)
  1094. The current date in numeric format: yyyymmdd, e.g. "20000208".
  1095. \v(time)
  1096. The current time as hh:mm:ss, e.g. "15:27:14".
  1097. \ftime(time)
  1098. The given free-format date and/or time (e.g. "3pm") returns the
  1099. time (without the date) converted to hh:mm:ss 24-hour format,
  1100. e.g. "15:00:00" (the date, if given, is ignored).
  1101. \v(ntime)
  1102. The current time as seconds since midnight, e.g. "55634".
  1103. \v(tftime)
  1104. The elapsed time of the most recent file-transfer operation in
  1105. seconds.
  1106. \v(intime)
  1107. The elapsed time for the most recent INPUT command to complete,
  1108. in milliseconds.
  1109. \fntime(time)
  1110. The given free-format date and/or time is converted to seconds
  1111. since midnight (the date, if given, is ignored). This function
  1112. replaces \ftod2secs(), which is now a synonym for \fntime().
  1113. Unlike \ftod2secs(), \fntime() allows a date to be included, and
  1114. it allows the time to be in free format (like 3pm), and it
  1115. allows the amount of time to be more than 24 hours. E.g.
  1116. \fntime(48:00:00) = 172800. Example of use:
  1117. set alarm \fntime(48:00:00) ; set alarm 48 hours from now.
  1118. \fn2time(seconds)
  1119. The given number of seconds is converted to hh:mm:ss format.
  1120. \fdate(filename)
  1121. Returns the modification date-time of the given file in standard
  1122. format: yyyymmdd hh:mm:ss.
  1123. \fcvtdate(date-time)
  1124. Converts a free-format date and/or time to Kermit standard
  1125. format: yyyymmdd hh:mm:ss. If no argument is given, returns the
  1126. current date-time in standard format. If a date is given but no
  1127. time, the converted date is returned without a time. If a time
  1128. is given with no date, the current date is supplied. Examples:
  1129. \fcvtdate(4 Jul 2000 2:21:17pm) = 20000704 14:21:17
  1130. \fcvtdate() = 20000704 14:21:17 (on 4 Jul 2000 at 2:21:17pm).
  1131. \fcvtd(4 Jul 2000) = 20000704
  1132. \fcvtd(6pm) = 20000704 18:00:00 (on 4 Jul 2000 at 6:00pm).
  1133. \fdayofyear(date-time)
  1134. \fdoy(date-time)
  1135. Converts a free-format date and/or time to yyyyddd, where ddd is
  1136. the 3-digit day of the year, and 1 January is Day 1. If a time
  1137. is included with the date, it is returned in standard format. If
  1138. a date is included but no time, the date is returned without a
  1139. time. If a time is given with no date, the time is converted and
  1140. the current date is supplied. If no argument is given, the
  1141. current date-time is returned. Synonym: \fdoy(). Examples:
  1142. \fddayofyear(4 Jul 2000 2:21:17pm) = 2000185 14:21:17
  1143. \fdoy() = 2000185 14:21:17 (on 4 Jul 2000 at 2:21:17pm).
  1144. \fdoy(4 Jul 2000) = 2000185
  1145. \fdoy(6pm) = 2000185 18:00:00 (on 4 Jul 2000 at 6:00pm).
  1146. Note: The yyyyddd day-of-year format is often erroneously referred to
  1147. as a Julian date. However, a true Julian date is a simple counting
  1148. number, the number of days since a certain fixed day in the past.
  1149. See \fmjd() below.
  1150. \fdoy2date(date-time)
  1151. Converts a date or date-time in day-of-year format to a standard
  1152. format date. A yyyyddd-format date must be supplied; time is
  1153. optional. The given date is converted to yyyymmdd format. If a
  1154. time is given, it is converted to 24-hour format. Examples:
  1155. \fdoy2date(2000185) = 20000704
  1156. \fdoy2(2000185 3pm) = 20000704 15:00:00
  1157. \fmjd(date-time)
  1158. Converts free-format date and/or time to a Modified Julian Date
  1159. (MJD), the number of days since 17 Nov 1858 00:00:00. If a time
  1160. is given, it is ignored. Examples:
  1161. \fmjd(4 Jul 2000) = 50998
  1162. \fmjd(17 Nov 1858) = 0
  1163. \fmjd(16 Nov 1858) = -1
  1164. \fmjd2date(mjd)
  1165. Converts an MJD (integer) to standard date format, yyyymmdd:
  1166. \fmjd2(50998) = 4 Jul 1998
  1167. \fmjd2(0) = 17 Nov 1858
  1168. \fmjd2(-1) = 16 Nov 1858
  1169. \fmjd2(-365) = 17 Nov 1857
  1170. MJDs are normal integers and, unlike DOYs, may be added, subtracted,
  1171. etc, with each other or with other integers, to obtain meaningful
  1172. results. For example, to find out the date 212 days ago:
  1173. echo \fmjd2date(\fmjd()-212)
  1174. Constructions such as this can be used in any command where a date-time
  1175. is required, e.g.:
  1176. send /after:\fmjd2date(\fmjd()-212)
  1177. to send all files that are not older than 212 days (this is equivalent
  1178. to "send /after:-212days").
  1179. MJDs also have other regularities not exhibited by other date formats.
  1180. For example, \fmodulus(\fmjd(any-date),7) gives the day of the week for
  1181. any date (where 4=Sun, 5=Mon, ..., 3=Sat). (However, it is easier to
  1182. use \fnday() for this purpose, and it gives the more conventional
  1183. result of 0=Sun, 1=Mon, ..., 6=Sat).
  1184. Note that if MJDs are to be compared, they must be compared numerically
  1185. (IF <, =, >) and not lexically (IF LLT, EQUAL, LGT), whereas DOYs must
  1186. be compared lexically if they include a time (which contains ":"
  1187. characters); however, if DOYs do not include a time, they may also be
  1188. compared numerically.
  1189. In any case, lexical comparison of DOYs always produces the appropriate
  1190. result, as does numeric comparison of MJDs.
  1191. The same comments apply to sorting. Also note that DOYs are fixed
  1192. length, but MJDs can vary in length. However, all MJDs between 3 April
  1193. 1886 and 30 Aug 2132 are 5 decimal digits long. (MJDs become 6 digits
  1194. long on 31 Aug 2132, and 7 digits long on 13 Oct 4596).
  1195. 1.7. Partial Completion of Keywords
  1196. Partial completion of keywords was added in C-Kermit 7.0. In prior
  1197. versions, if completion was attempted (by pressing the Esc or Tab key)
  1198. on a string that matched different keywords, you'd just get a beep. Now
  1199. Kermit completes up to the first character where the possibly matching
  1200. keywords differ and then beeps. For example:
  1201. C-Kermit> send /n<Tab>
  1202. which matches /NOT-BEFORE and /NOT-AFTER, now completes up to the dash:
  1203. C-Kermit> send /n<Tab>ot-<Beep>
  1204. Partial completion works for filenames too (as it has for some years).
  1205. 1.8. Command Recall
  1206. C-Kermit has had a command history buffer for some time, which could be
  1207. scrolled interactively using control characters or (in Kermit 95 only)
  1208. arrow keys. Version 7.0 adds a REDO command that allows the most recent
  1209. command matching a given pattern to be re-executed:
  1210. { REDO, RR, ^ } [ pattern ]
  1211. Search the command history list for the most recent command that
  1212. matches the given pattern, and if one is found, execute it
  1213. again.
  1214. The pattern can be a simple string (like "send"), in which case the
  1215. last SEND command is re-executed. Or it can contain wildcard characters
  1216. "*" and/or "?", which match any string and any single character,
  1217. respectively (note that "?" must be preceded by backslash to override
  1218. its normal function of giving help), and in most C-Kermit versions may
  1219. also include [] character lists and {} string lists (seeSection
  1220. 4.9).
  1221. The match works by appending "*" to the end of the given pattern (if
  1222. you didn't put one there yourself). Thus "redo *oofa" becomes "redo
  1223. *oofa*" and therefore matches the most recent command that contains
  1224. "oofa" anywhere within the command. If you want to inhibit the
  1225. application of the trailing "*", e.g. to force matching a string at the
  1226. end of a command, enclose the pattern in braces:
  1227. redo {*oofa}
  1228. matches the most recent command that ends with "oofa".
  1229. REDO commands themselves are not entered into the command history list.
  1230. If no pattern is given, the previous (non-REDO) command is re-executed.
  1231. The REDOne command is reinserted at the end of the command history
  1232. buffer, so the command scrollback character (Ctrl-P, Ctrl-B, or
  1233. Uparrow) can retrieve it.
  1234. Examples:
  1235. C-Kermit> echo foo
  1236. foo
  1237. C-Kermit> show alarm
  1238. (no alarm set)
  1239. C-Kermit> echo blah
  1240. blah
  1241. C-Kermit> redo ; Most recent command
  1242. blah
  1243. C-Kermit> redo s ; Most recent command starting with "s"
  1244. (no alarm set)
  1245. C-Kermit> redo echo f ; Most recent command starting with "echo f"
  1246. foo
  1247. C-Kermit> redo *foo ; Most recent command that has "foo" in it
  1248. foo
  1249. C-Kermit> <Ctrl-P> ; Scroll back
  1250. C-Kermit> echo foo ; The REDOne command is there
  1251. C-Kermit> redo {*foo} ; Most recent command that ends with "foo"
  1252. foo
  1253. C-Kermit>
  1254. Since REDO, REDIAL, and REDIRECT all start the same way, and RED is the
  1255. designated non-unique abbreviation for REDIAL, REDO must be spelled out
  1256. in full. For convenience, RR is included as an invisible easy-to-type
  1257. synonym for REDO. You can also use the "^" character for this:
  1258. C-Kermit> ^ ; Most recent command
  1259. C-Kermit> ^ s ; Most recent command starting with "s"
  1260. C-Kermit> ^s ; Ditto (space not required after "^").
  1261. C-Kermit> ^*foo ; Most recent command that has "foo" in it.
  1262. C-Kermit> ^{*foo} ; Most recent command ends with "foo".
  1263. Unlike the manual command-history-scrolling keys, the REDO command can
  1264. be used in a script, but it's not recommended (since the command to be
  1265. REDOne might not be found, so if the REDO command fails, you can't tell
  1266. whether it was because REDO failed to find the requested command, or
  1267. because the command was found but it failed).
  1268. 1.9. EXIT Messages
  1269. The EXIT and QUIT commands now accept an optional message to be
  1270. printed. This makes the syntax of EXIT and QUIT just like END and STOP:
  1271. { EXIT, QUIT, END, STOP } [ status-code [ message ] ]
  1272. where status-code is a number (0 indicating success, nonzero indicating
  1273. failure). This is handy in scripts that are never supposed to enter
  1274. interactive mode:
  1275. dial 7654321
  1276. if fail exit 1 Can't make connection - try again later.
  1277. Previously this could only be done in two steps:
  1278. dial 7654321
  1279. xif fail { echo Can't make connection - try again later, exit 1 }
  1280. A status code must be included in order to specify a message. In the
  1281. case of EXIT and QUIT, the default status code is contained in the
  1282. variable \v(exitstatus), and is set automatically by various events
  1283. (file transfer failures, etc; it can also be set explicitly with the
  1284. SET EXIT STATUS command). If you want to give an EXIT or QUIT command
  1285. with a message, but without changing the exit status from what it
  1286. normally would have been, use the \v(exitstatus) variable, e.g.:
  1287. exit \v(exitstatus) Goodbye from \v(cmdfile).
  1288. The EXIT status is returned to the system shell or whatever other
  1289. process invoked C-Kermit, e.g. in UNIX:
  1290. C-Kermit> exit 97 bye bye
  1291. bye bye
  1292. $ echo $?
  1293. 97
  1294. $
  1295. 1.10. Managing Keyboard Interruptions
  1296. When C-Kermit is in command or file-transfer mode (as opposed to
  1297. CONNECT mode), it can be interrupted with Ctrl-C. Version 7.0 adds the
  1298. ability to disarm the Ctrl-C interrupt:
  1299. SET COMMAND INTERRUPT { ON, OFF }
  1300. COMMAND INTERRUPT is ON by default, meaning the Ctrl-C can be
  1301. used to interrupt a command or a file transfer in progress. Use
  1302. OFF to disable these interruptions, and use it with great
  1303. caution for obvious reasons.
  1304. SET TRANSFER INTERRUPT { ON, OFF }
  1305. This can be used to disable keyboard interruption of file
  1306. transfer when C-Kermit is in local mode, or to re-enable it
  1307. after it has been disabled. This applies to the X, Z, E, and
  1308. similar keys as well as to the system interrupt character,
  1309. usually Ctrl-C. This is distinct from SET TRANSFER CANCELLATION,
  1310. which tells whether packet mode can be exited by sending a
  1311. special sequence of characters.
  1312. Several other commands can be interrupted by pressing any key while
  1313. they are active. Version 7.0 adds the ability to disable this form of
  1314. interruption also:
  1315. SET INPUT CANCELLATION { ON, OFF }
  1316. Whether an INPUT command in progress can be interrupted by
  1317. pressing a key. Normally ON. Setting INPUT CANCELLATION OFF
  1318. makes INPUT commands uninterruptible except by Ctrl-C (unless
  1319. COMMAND INTERRUPTION is also OFF).
  1320. SET SLEEP CANCELLATION { ON, OFF }
  1321. Whether a SLEEP, PAUSE, or WAIT command in progress can be
  1322. interrupted by pressing a key. Normally ON. Setting SLEEP
  1323. CANCELLATION OFF makes these commands uninterruptible except by
  1324. Ctrl-C (unless COMMAND INTERRUPTION is also OFF). Synonyms: SET
  1325. PAUSE CANCELLATION, SET WAIT CANCELLATION.
  1326. So to make certain a script is not interruptible by the user, include
  1327. these commands:
  1328. SET TRANSFER INTERRUPT OFF
  1329. SET SLEEP CANCELLATION OFF
  1330. SET INPUT CANCELLATION OFF
  1331. SET COMMAND INTERRUPTION OFF
  1332. Make sure to turn them back on afterwards if interruption is to be
  1333. re-enabled.
  1334. When a PAUSE, SLEEP, WAIT, or INPUT command is interrupted from the
  1335. keyboard, the new variable \v(kbchar) contains a copy of the (first)
  1336. character that was typed and caused the interruption, provided it was
  1337. not the command interrupt character (usually Ctrl-C). If these commands
  1338. complete successfully or time out without a keyboard interruption, the
  1339. \v(kbchar) variable is empty.
  1340. The \v(kbchar) variable (like any other variable) can be tested with:
  1341. if defined \v(kbchar) command
  1342. The command is executed if the variable is not empty.
  1343. The \v(kbchar) variable can be reset with WAIT 0 (PAUSE 0, SLEEP 0,
  1344. etc).
  1345. 1.11. Taming The Wild Backslash -- Part Deux
  1346. Using C-Kermit, 2nd Edition, contains a brief section, "Taming the
  1347. Wild Backslash", on page 48, which subsequent experience has shown to
  1348. be inadequate for Kermit users intent on writing scripts that deal with
  1349. Windows, DOS, and OS/2 filenames, in which backslash (\) is used as the
  1350. directory separator. This section fills in the blanks.
  1351. 1.11.1. Background
  1352. The Kermit command language shares a certain unavoidable but annoying
  1353. characteristic with most other command languages that are capable of
  1354. string replacement, namely the necessity to "quote" certain characters
  1355. when you want them to be taken literally. This is a consequence of the
  1356. facts that:
  1357. 1. One or more characters must be set aside to denote replacement,
  1358. rather than acting as literal text.
  1359. 2. We have only 96 printable characters to work with in ASCII, which
  1360. is still the only universally portable character set.
  1361. 3. There is no single printable character that is unused everywhere.
  1362. 4. Variables are not restricted to certain contexts, as they are in
  1363. formal programming languages like C and Fortran, but can appear
  1364. anywhere at all within a command, and therefore require special
  1365. syntax.
  1366. Thus there can be conflicts. To illustrate, the standard UNIX shell
  1367. uses dollar sign ($) to introduce variables. So the shell command:
  1368. echo $TERM
  1369. displays the value of the TERM variable, e.g. vt320. But suppose you
  1370. want to display a real dollar sign:
  1371. echo The price is $10.20
  1372. This causes the shell to evaluate the variable "$1", which might or
  1373. might not exist, and substitute its value, e.g.:
  1374. The price is 0.20
  1375. (in this case the $1 variable had no value.) This is probably not what
  1376. you wanted. To force the dollar sign to be taken literally, you must
  1377. apply a "quoting rule", such as "precede a character by backslash (\)
  1378. to force the shell to take the character literally":
  1379. echo The price is \$10.20
  1380. The price is $10.20
  1381. But now suppose you want the backslash AND the dollar sign to be taken
  1382. literally:
  1383. echo The price is \\$10.20
  1384. This doesn't work, since the first backslash quotes the second one,
  1385. thereby leaving the dollar sign unquoted again:
  1386. The price is \0.20
  1387. Quoting the dollar sign requires addition of a third backslash:
  1388. echo The price is \\\$10.20
  1389. The price is \$10.20
  1390. The first backslash quotes the second one, and the third backslash
  1391. quotes the dollar sign.
  1392. Every command language -- all UNIX shells, VMS DCL, DOS Batch, AOS/VS
  1393. CLI, etc etc -- has similar rules. UNIX shell rules are probably the
  1394. most complicated, since many printable characters -- not just one --
  1395. are special there: dollar sign, single quote, double quote, backslash,
  1396. asterisk, accent grave, number sign, ampersand, question mark,
  1397. parentheses, brackets, braces, etc -- practically every
  1398. non-alphanumeric character needs some form of quoting if it is to be
  1399. taken literally. And to add to the confusion, the UNIX shell offers
  1400. many forms of quoting, and many alternative UNIX shells are available,
  1401. each using slightly different syntax.
  1402. 1.11.2. Kermit's Quoting Rules
  1403. Kermit's basic quoting rules are simple by comparison (there are, of
  1404. course, additional syntax requirements for macro definitions, command
  1405. blocks, function calls, etc, but they are not relevant here).
  1406. The following characters are special in Kermit commands:
  1407. Backslash (\)
  1408. Introduces a variable, or the numeric representation of a
  1409. special character, or a function, or other item for
  1410. substitution. If the backslash is followed by a digit or by any
  1411. of the following characters:
  1412. x, o, d, m, s, f, v, $, %, &, :, {
  1413. this indicates a special substitution item; otherwise the
  1414. following character is to be taken literally (exceptions: \ at
  1415. end of line is taken literally; \n, \b, and \n are special items
  1416. in the OUTPUT command only).
  1417. Semicolon (;)
  1418. (Only when at the beginning of a line or preceded by at least
  1419. one space or tab) Introduces a comment.
  1420. Number sign (#)
  1421. (Only when at the beginning of a line or preceded by at least
  1422. one space or tab) Just like semicolon; introduces a comment.
  1423. Question mark (?)
  1424. (Only at the command prompt - not in command files or macros)
  1425. Requests context-sensitive help.
  1426. To force Kermit to take any of these characters literally, simply
  1427. precede it by a backslash (\).
  1428. Sounds easy! And it is, except when backslash also has a special
  1429. meaning to the underlying operating system, as it does in DOS, Windows,
  1430. and OS/2, where it serves as the directory separator in filenames such
  1431. as:
  1432. D:\K95\KEYMAPS\READ.ME
  1433. Using our rule, we would need to refer to this file in Kermit commands
  1434. as follows:
  1435. D:\\K95\\KEYMAPS\\READ.ME
  1436. But this would not be obvious to new users of Kermit software on DOS,
  1437. Windows, or OS/2, and it would be annoying to seasoned ones. Thus
  1438. MS-DOS Kermit and Kermit 95 go to rather extreme lengths to allow the
  1439. more natural notation, as in:
  1440. send d:\k95\keymaps\read.me
  1441. The reason this is tricky is that we also need to allow for variables
  1442. and other expressions introduced by backslash in the same command. For
  1443. example, suppose \%a is a variable whose value is "oofa" (without the
  1444. quotes). What does the following command do?
  1445. send d:\%a
  1446. Does it send the file named "oofa" in the current directory of the D:
  1447. disk, or does it send a file named "%a" in the root directory of the D:
  1448. disk? This is the kind of trouble we get into when we attempt to bend
  1449. the rules in the interest of user friendliness. (The answer is: if the
  1450. variable \%a has definition that is the name of an existing file, that
  1451. file is sent; if a file d:\%a exists, it is sent; otherwise if both
  1452. conditions are true, the variable takes precedence, and the literal
  1453. filename can be forced by quoting: \\%a.)
  1454. In Kermit 95 (but not MS-DOS Kermit), we also bend the rules another
  1455. way by allowing you to use forward slash (/) rather than backslash (\)
  1456. as the directory separator:
  1457. send d:/k95/keymaps/read.me
  1458. This looks more natural to UNIX users, and in fact is perfectly
  1459. acceptable to the Windows 95/98/NT and OS/2 operating systems on the
  1460. API level. BUT (there is always a "but") the Microsoft shell,
  1461. COMMAND.COM, for Windows 95/98 and NT does not allow this notation, and
  1462. therefore it can not be used in any Kermit command -- such as RUN --
  1463. that invokes the Windows command shell AND your command shell is
  1464. COMMAND.COM or any other shell that does not allow forward slash as
  1465. directory separator (some alternative shells do allow this).
  1466. NOTE: There exists a wide variety of alternative shells from third
  1467. parties that do not have this restriction. If you are using a shell
  1468. that accepts forward slash as a directory separator, you can stop
  1469. reading right now -- UNLESS (there is always an "unless") you want
  1470. your scripts to be portable to systems that have other shells. Also
  1471. note that some Windows shells might actually REQUIRE forward slashes
  1472. (instead of backslashes) as directory separators; we do not treat
  1473. this situation below, but the treatment is obvious -- use slash
  1474. rather backslash as the directory separator.
  1475. 1.11.3. Passing DOS Filenames from Kermit to Shell Commands
  1476. The following Kermit commands invoke the system command shell:
  1477. RUN (and its synonyms ! and @)
  1478. REDIRECT
  1479. PIPE
  1480. Each of these commands takes a shell command as an operand. These shell
  1481. commands are not, and can not be, parsed by Kermit since Kermit does
  1482. not know the syntax of shell commands, and so can't tell the difference
  1483. between a keyword, a filename, a variable, a switch, or other item.
  1484. Therefore the rules can not be bent since Kermit doesn't know where or
  1485. how to bend them. To illustrate (using the regular Windows shell):
  1486. run c:\\windows\\command\\chkdsk.exe
  1487. works OK, but:
  1488. run c:/windows/command/chkdsk.exe
  1489. is not accepted by COMMAND.COM. But:
  1490. run c:\windows\command\chkdsk.exe
  1491. results in Kermit applying its quoting rules before sending the text to
  1492. the shell. Since "w" and "c" are not in the list of backslash-item
  1493. codes, the backslash means "take the following character literally".
  1494. Thus, by the time this filename gets to the Windows shell, it has
  1495. become:
  1496. c:windowscommandchkdsk.exe
  1497. which is probably not what you wanted. (If "w" and "c" were in the
  1498. list, the results could be even stranger.) Even more confusing is the
  1499. case where a directory or filename starts with one or more digits:
  1500. run c:\123\lotus.exe
  1501. in which "\123" is the Kermit notation for ASCII character 123, which
  1502. happens to be left brace ({), resulting in "c:{lotus.exe".
  1503. So when passing filenames to a Windows shell, always use double
  1504. backslashes as directory separators, to ensure that the shell gets
  1505. single backslashes:
  1506. run c:\\windows\\command\\chkdsk.exe
  1507. run c:\\123\\lotus.exe
  1508. Similar problems might occur with the built-in EDIT, BROWSE, and FTP
  1509. commands. These commands result in Kermit building a shell command
  1510. internally to invoke the associated helper program; the form of this
  1511. command might conflict with the form demanded by certain alternative
  1512. shells.
  1513. 1.11.4. Using Variables to Hold DOS Filenames
  1514. Now to the next level. Suppose you want to write a script in which
  1515. filenames are parameters, and therefore are stored in variables.
  1516. Example:
  1517. define \%f c:\windows\command\chkdsk.exe
  1518. ...
  1519. run \%f
  1520. Obviously this won't work for the reasons just noted; the RUN command
  1521. requires directory separators be coded as double backslashes:
  1522. define \%f c:\\windows\\command\\chkdsk.exe
  1523. ...
  1524. run \%f
  1525. This will work; no surprises here. However, if you had used ASSIGN
  1526. rather than DEFINE, you might have been surprised after all; review
  1527. pages 348-349 ofUsing C-Kermit (2nd Ed) for the difference
  1528. between DEFINE and ASSIGN.
  1529. We have said that any Kermit 95 or MS-DOS Kermit command that parses
  1530. filenames itself -- SEND, for example -- does not require double
  1531. backslashes since it knows it is parsing a filename. So since the
  1532. following works:
  1533. send c:\windows\command\chkdsk.exe
  1534. Should the following also work?
  1535. define \%f c:\windows\command\chkdsk.exe
  1536. ...
  1537. send \%f
  1538. Answer: No. Why? Because \%f is evaluated "recursively", to allow for
  1539. the possibility that its definition contains further variable
  1540. references. This is true of all "backslash-percent-letter" (or -digit)
  1541. variables, and also for array references. So \%f becomes
  1542. c:\windows\command\chkdsk.exe, which becomes
  1543. c:windowscommandchkdsk.exe.
  1544. The trick here is to use the "other" kind of variable, that is
  1545. evaluated only "one level deep" rather than recursively:
  1546. define filename c:\windows\command\chkdsk.exe
  1547. ...
  1548. send \m(filename)
  1549. Similarly if you want to prompt the user for a filename:
  1550. ask filename { Please type a filename: }
  1551. Please type a filename: c:\windows\command\chkdsk.exe
  1552. send \m(filename)
  1553. 1.11.5. Passing DOS Filenames as Parameters to Macros
  1554. Suppose you want to pass a DOS filename containing backslashes as a
  1555. parameter to a Kermit macro. This raises two issues:
  1556. 1. Parameters to macros are "just text" and so are fully evaluated
  1557. before they are passed to the macro.
  1558. 2. Once inside the macro, the formal parameters \%1, \%2, ... \%9 are
  1559. the type of variable that is evaluated recursively.
  1560. Thus a DOS filename is ruined once in the act of parsing the macro
  1561. invocation, and again when referring to it from within the macro. To
  1562. illustrate, suppose "test" is a macro. Then in the invocation:
  1563. test c:\mydir\blah.txt
  1564. "c:mydirblah.txt" is assigned to \%1. However, if we double the
  1565. backslashes:
  1566. test c:\\mydir\\blah.txt
  1567. "c:\mydir\blah.txt" is assigned to \%1. But then when you refer to \%1
  1568. in the macro, it is evaluated recursively, resulting in
  1569. "c:mydirblah.txt". To illustrate:
  1570. define test echo \%1
  1571. test c:\mydir\blah.txt
  1572. c:mydirblah.txt
  1573. test c:\\mydir\\blah.txt
  1574. c:mydirblah.txt
  1575. test c:\\\\mydir\\\\blah.txt
  1576. c:\mydir\blah.txt
  1577. Let's address each part of the problem separately. First, inside the
  1578. macro. You can use the \fcontents() function to force a
  1579. backslash-percent variable (such as a macro argument) to be evaluated
  1580. one level deep instead of recursively, for example:
  1581. define test echo { The filename is "\fcontents(\%1)"}
  1582. test c:\mydir\blah.txt ; We don't expect this to work
  1583. The filename is "c:mydirblah.txt" ; and it doesn't.
  1584. test c:\\mydir\\blah.txt ; But this does...
  1585. The filename is "c:\mydir\blah.txt"
  1586. Thus if the filename arrives inside the macro with single backslashes,
  1587. the backslashes are preserved if you always refer to the parameter
  1588. through the \fcontents() function.
  1589. Now how to ensure that backslashes are not stripped or misinterpreted
  1590. when passing a filename to a macro? This brings us back to what we
  1591. learned in earlier sections:
  1592. 1. If it is a literal filename, either double the backslashes, or (if
  1593. the filename is to be used only within Kermit itself and not passed
  1594. to a DOS shell, or it is to be passed to an alternative shell that
  1595. accepts forward slash as a directory separator), use forward slash
  1596. instead of backslash as the directory separator.
  1597. 2. If it is a variable that contains a filename, make sure you use a
  1598. macro-style variable name, rather than a
  1599. backslash-percent-character name.
  1600. Examples:
  1601. define test echo \fcontents(\%1)
  1602. define filename c:\mydir\blah.txt
  1603. test c:\\mydir\\blah.txt ; Literal filename with double backslashes
  1604. c:\mydir\blah.txt
  1605. test c:/mydir/blah.txt ; Literal filename with forward slashes
  1606. c:/mydir/blah.txt
  1607. test \m(filename) ; Variable
  1608. c:\mydir\blah.txt
  1609. But what if you don't like these rules and you still want to pass a
  1610. literal filename containing single backslashes to a macro? This is
  1611. possible too, but a bit tricky: turn command quoting off before
  1612. invoking the macro, and then turn it back on inside the macro. Example:
  1613. define test set command quoting on, echo \fcontents(\%1)
  1614. set command quoting off
  1615. test c:\mydir\blah.txt
  1616. c:\mydir\blah.txt
  1617. Upon return from the macro, command quoting is back on (since the macro
  1618. turned it on).
  1619. Obviously this trick can not be used if the filename is stored in a
  1620. variable, since it prevents the variable from being evaluated.
  1621. 1.11.6. Passing DOS File Names from Macro Parameters to the DOS Shell
  1622. Now suppose you need to pass a DOS filename to a macro, and the macro
  1623. needs to pass it, in turn, to the Windows shell via (say) Kermit's RUN
  1624. command. This works too:
  1625. define xrun run \fcontents(\%1)
  1626. xrun c:\\windows\\command\\chkdsk.exe
  1627. (or you can use the SET COMMAND QUOTING OFF / ON technique described
  1628. above to avoid the double backslashes.) But..
  1629. xrun c:/windows/command/chkdsk.exe
  1630. does not work if the Windows shell does not recognize "/" as a
  1631. directory separator. If there is a chance that a filename might be
  1632. passed to the macro in this form, the macro will need to convert it to
  1633. a form acceptable to the shell:
  1634. define xrun run \freplace(\fcontents(\%1),/,\\)
  1635. Here we replace all occurrences (if any) of "/" in the argument with
  1636. "\" prior to issuing the RUN command. Of course, in order to specify
  1637. "\" as a literal character in the \freplace() argument list, we have to
  1638. double it.
  1639. 1.11.7. Passing DOS Filenames to Kermit from the Shell
  1640. As noted in the manual, the \&@[] array contains Kermit's command-line
  1641. arguments. Suppose one of these arguments, say \&@[3], is a DOS
  1642. filename such as C:\FOO\BAR\BAZ\OOFA.TXT. (Note: In C-Kermit 7.0 and
  1643. K95 1.1.18 and later, command-line arguments after "=" or "--" are also
  1644. available in the top-level \%1..9 variables; see Section 7.5.)
  1645. Of course you can eliminate any problems by using forward slashes
  1646. rather than backslashes in the filename, but sometimes this is not
  1647. possible, as when the Kermit command line is being generated by another
  1648. program than can only generate "native" format DOS filenames.
  1649. As noted in the manual, "\%x" variables and \&x[] arrays are always
  1650. evaluated "all the way" (recursively). If the contents of one of these
  1651. variables contains backslashes, this causes another level of
  1652. evaluation.
  1653. There is another kind of variable, which is evaluated only "one level
  1654. deep". You can use this to prevent interpretation of the backslashes in
  1655. the filenames. Example:
  1656. assign filename \fcontents(\&@[3]) ; Transfer contents
  1657. ...
  1658. send \m(filename)
  1659. Or, more simply:
  1660. send \fcontents(\&@[3])
  1661. 1.12. Debugging
  1662. The debug log is produced when you give a "log debug" command. This is
  1663. normally done at the request of the Kermit help desk, for forwarding to
  1664. the Kermit developers for analysis as a last resort in troubleshooting
  1665. problems. (Last resort because it can grow quite huge in a very short
  1666. time.) In cases where timing information is critical to understanding a
  1667. problem, you can tell C-Kermit to put a timestamp on each debug log
  1668. line by giving the command:
  1669. SET DEBUG TIMESTAMP ON
  1670. At any time before or after activating the debug log (SET DEBUG
  1671. TIMESTAMP OFF turns off timestamping). Timestamps can be turned off and
  1672. on as desired while logging. Obviously, they increase the size and
  1673. growth rate of the log significantly, and so should be used sparingly.
  1674. Timestamps are of the form hh:mm:ss.xxx, where .xxx is thousands of a
  1675. second (but is included only on platforms that include this feature).
  1676. 1.13. Logs
  1677. In UNIX C-Kermit and in K-95, you can now direct any log to a pipe.
  1678. This not only lets you send your logs to places other than disk files,
  1679. but also lets you customize them to any desired degree.
  1680. LOG { DEBUG, PACKETS, SESSION, TRANSACTION, CONNECTION } { file, pipe }
  1681. ...
  1682. A "pipe" is the name of a command, preceded by a vertical bar.
  1683. If the pipe contains any spaces, it must be enclosed in braces.
  1684. Here are some examples for UNIX (always remember the importance of
  1685. getting the UNIX shell quoting rules right):
  1686. LOG TRANSACTIONS |lpr
  1687. This sends the transaction log to the default UNIX printer,
  1688. rather than to a file (use "lp" rather than "lpr" if necessary).
  1689. LOG TRANSACTIONS {| myfilter > t.log}
  1690. For those who don't like the format of the transaction log, or
  1691. want to extract certain information from it; write your own
  1692. output filter.
  1693. LOG SESSION {| lpr -Plaserwriter}
  1694. This sends the session log to a specific UNIX printer, rather
  1695. than to a file. Note the braces around the pipeline. These are
  1696. required because it contains spaces.
  1697. LOG DEBUG {| tail -100 > debug.log}
  1698. This causes the debug log file to contain only the final 100
  1699. lines. Suppose C-Kermit crashes under some unpredictable
  1700. circumstances, and you need a debug log to catch it in the act.
  1701. But the debug log can grow to huge proportions very quickly,
  1702. possibly filling up the disk. Piping the debug log through
  1703. "tail" results in keeping only the last 100 lines (or other
  1704. number of your choice).
  1705. LOG DEBUG {| grep "^TELNET" > debug.log}
  1706. This one shows how to log only Telnet negotiations. Piping the
  1707. debug log through grep or egrep lets you log only specific
  1708. information, rather than everything. "man grep" for further
  1709. info.
  1710. LOG DEBUG {| gzip -c > debug.log.gz}
  1711. Creates a full debug log, but compressed by gzip to save space.
  1712. LOG PACKETS {| tr "\\01" "X" | cut -c9- > packet.log}
  1713. This one writes the regular packet log, but translates the
  1714. Ctrl-A that starts each packet to the letter "X" and removes the
  1715. s-nn-nn- notation from the beginning of each line. Note the
  1716. double backslash (normal Kermit quoting rules). "man tr" and
  1717. "man cut" for further info.
  1718. See Section 2.12 for information about the new connection log.
  1719. 1.14. Automatic File-Transfer Packet Recognition at the Command Prompt
  1720. Beginning in version 7.0, C-Kermit can recognize Kermit (and in some
  1721. cases also Zmodem) file-transfer packets while at its command prompt.
  1722. This is convenient (for example), if you escaped back from a remote
  1723. Kermit program and told the local Kermit program to send a file, but
  1724. forgot to tell the remote Kermit program to receive it (and the local
  1725. Kermit did not have the "send a Kermit receive command" feature
  1726. available). This feature is controlled by the following command:
  1727. SET COMMAND AUTODOWNLOAD { ON, OFF }
  1728. When ON, which is the default, the command parser recognizes
  1729. Kermit packets when Kermit is in remote mode. An S packet makes
  1730. it go into receive mode, an I packet makes it go into server
  1731. mode. When OFF, packet recognition is disabled and the behavior
  1732. when a packet is received at the command prompt is as it was in
  1733. C-Kermit 6.1 and earlier (namely to print an error message).
  1734. COMMAND AUTODOWNLOAD is the command-mode equivalent of TERMINAL
  1735. AUTODOWNLOAD, which is effective during CONNECT mode.
  1736. 1.15. The TYPE Command
  1737. The TYPE command now accepts a selection of optional switches
  1738. ( Section 1.5), and also sets several variables.
  1739. Syntax: TYPE [ switches... ] filename
  1740. Variables:
  1741. \v(ty_ln)
  1742. Line number of current line (during TYPE command; see /PREFIX)
  1743. \v(ty_lc)
  1744. Line count of file most recently TYPEd.
  1745. \v(ty_mc)
  1746. Match count of file most recently TYPEd (see /MATCH).
  1747. Switches:
  1748. /PAGE
  1749. If /PAGE is included, Kermit pauses at the end of each screenful
  1750. and issues a "more?" prompt. You may press the space bar to view
  1751. the next page (screenful), or press "q" or "n" to return to the
  1752. C-Kermit prompt. If this switch is given, it overrides the
  1753. COMMAND MORE-PROMPTING setting for this command only. If it is
  1754. not given, paging is according to COMMAND MORE-PROMPTING.
  1755. /NOPAGE
  1756. Do not pause at the end of each screenful; show the whole file
  1757. (or all selected lines) at once. If this switch is given, it
  1758. overrides the COMMAND MORE-PROMPTING setting for this command
  1759. only. If it is not given, paging is according to COMMAND
  1760. MORE-PROMPTING.
  1761. /HEAD[:n]
  1762. Only show the first n lines of the file (where n is a number).
  1763. If n is omitted, 10 is used.
  1764. /TAIL[:n]
  1765. Only show the last n lines of the file (where n is a number). If
  1766. nis omitted, 10 is used. Note: /HEAD and /TAIL can't be
  1767. combined; if you give both switches, only the most recent one is
  1768. used.
  1769. /MATCH:pattern
  1770. Only type lines from the file that match the given pattern (see
  1771. Section 4.9.1 for pattern notation). UNIX users familiar
  1772. with grep should note a significant difference: there is no
  1773. implied "*" at the beginning and end of the pattern. Thus:
  1774. TYPE /MATCH:foo Lists lines whose entire contents are "foo".
  1775. TYPE /MATCH:foo* Lists lines that start with "foo".
  1776. TYPE /MATCH:*foo Lists lines that end with "foo".
  1777. TYPE /MATCH:*foo* Lists lines that have "foo" anywhere in them.
  1778. /HEAD and /TAIL apply after /MATCH, so "type /tail:20 /match:x*"
  1779. shows the last 20 lines in the file that start with "x".
  1780. /PREFIX:string
  1781. Print the given string at the beginning of each line. The string
  1782. may be a constant, a variable, or a quoted variable. If it's an
  1783. unquoted variable, its value at the time the TYPE command was
  1784. given is used as a constant. If it is a quoted variable, it is
  1785. re-evaluated for each line; a useful variable for this context
  1786. is \v(ty_ln) (the line number of the current line being typed).
  1787. If the prefix is to include spaces, it must be enclosed in
  1788. braces. Examples:
  1789. type /prefix:{oofa.txt: } /match:*thing* oofa.txt
  1790. Prints all lines in oofa.txt that contain "thing" with the
  1791. filename itself as the prefix (similar to UNIX grep).
  1792. type /prefix:{\v(time). } oofa.txt
  1793. Prefixes each line of oofa.txt with the time at which the
  1794. TYPE command was given (one backslash)
  1795. type /prefix:{\\v(time). } oofa.txt
  1796. Prefixes each line of oofa.txt with the time at which that
  1797. line is being typed (two backslashes).
  1798. type /prefix:{\\v(ty_ln). } oofa.txt
  1799. Prefixes each line of oofa.txt with its line number.
  1800. type /prefix:{\\flpad(\\v(ty_ln),4). } oofa.txt
  1801. Same as the previous example, except the line number is
  1802. right-adjusted in a 4-column field.
  1803. /WIDTH[:n]
  1804. Truncates each line at column n (which must be a number) prior
  1805. to printing it. This option can be used for long lines when you
  1806. don't want them to wrap. If nis omitted, your current screen
  1807. width is used.
  1808. /COUNT
  1809. Counts lines and -- if /MATCH was included, matches -- but does
  1810. not print any lines from the file. The line and match count is
  1811. shown at the end, and the variables \v(ty_lc) and \v(ty_lm) are
  1812. set accordingly.
  1813. SET OPTIONS TYPE { /PAGE, /NOPAGE, /WIDTH:n }
  1814. Sets the paging default for TYPE commands, which can be
  1815. overridden in any particular TYPE command by including the
  1816. desired switch.
  1817. If a TYPE command is given with no switch, and no SET OPTIONS TYPE
  1818. selection is in effect, paging is according to your COMMAND
  1819. MORE-PROMPTING setting (SHOW COMMAND).
  1820. 1.16. The RESET Command
  1821. The RESET command, added in 7.0, closes all open files and logs, but
  1822. does not affect the open connection (if any).
  1823. 1.17. The COPY and RENAME Commands
  1824. As of C-Kermit 7.0, in the UNIX version only, the COPY and RENAME
  1825. commands are built in and do not call the underlying platform's COPY or
  1826. RENAME command. This allows them to work in "NOPUSH" versions and other
  1827. circumstances where it can't access system commands, and it allows file
  1828. copying and renaming to be done portably in scripts. The
  1829. characteristics of the built-in COPY or RENAME include:
  1830. * It fails if the source file is a directory or is wild or lacks read
  1831. access.
  1832. * It fails if the source file is the destination file.
  1833. * It allows the destination file to be a directory, in which case the
  1834. source file is copied (or renamed) into it with the same name.
  1835. * It overwrites an existing destination file if its permission
  1836. allows.
  1837. * It sets the new file's permission according to umask but also
  1838. carries forward the source file's execute permission bits if the
  1839. destination file did not already exist.
  1840. * It fails if interrupted by Ctrl-C.
  1841. * Upon error, it prints an appropriate message.
  1842. * It returns standardized error codes that can be tested by IF
  1843. SUCCESS / FAIL.
  1844. These commands now also accept the following switches:
  1845. /LIST (/LOG, /VERBOSE) = Print "file1 => file2 (OK)" (or error message).
  1846. /NOLIST (/NOLOG, /QUIET) = Don't print anything (except error messages).
  1847. /NOLIST is the default.
  1848. The same built-in code is used by the UNIX C-Kermit server to execute
  1849. REMOTE COPY commands (except in this case no switches are available).
  1850. The COPY command also accepts the following additional switches. When
  1851. any of these are given (and they can be used in any combination except
  1852. /SWAP and /APPEND), some of the checks listed above are relaxed, and
  1853. thus it might be possible to get into trouble in certain cases, e.g.
  1854. when the source and target files are the same file:
  1855. /APPEND = Append source file to destination file.
  1856. /SWAP-BYTES = Swap bytes (see Section 6.6.5).
  1857. /FROMB64 = Decode the source file from Base64 encoding.
  1858. /TOB64 = Encode the target file in Base64.
  1859. Base64 is the encoding commonly used for enclosures in Internet email.
  1860. 1.18. The MANUAL Command
  1861. The MANUAL command can be used to access the appropriate Kermit manual
  1862. or other manual. The general syntax is:
  1863. MANUAL [ string ]
  1864. If the string is omitted, C-Kermit asks the underlying system to
  1865. access the C-Kermit manual using whatever method is appropriate
  1866. for the system.
  1867. The specific action depends on the system. In UNIX, a "man" command is
  1868. issued; "kermit" is the default argument but other manual topics may be
  1869. specified. If the "man" command allows index or string searching, the
  1870. appropriate syntax may be included.
  1871. In Kermit 95, the MANUAL command brings up the HTML online K95 manual.
  1872. In VMS and elsewhere, "man" is simply translated to "help", with a
  1873. default argument of "kermit"; other and/or additional arguments may be
  1874. included according to the definition of the system's "help" command.
  1875. Correct operation of the "man" command in C-Kermit depends on the
  1876. appropriate man page or help topic having been installed in the right
  1877. place with the right permissions and format.
  1878. 1.19. String and Filename Matching Patterns
  1879. A pattern is a string that includes special notation for matching
  1880. classes or sequences of characters. C-Kermit 7.0 / K95 1.1.19 supports
  1881. patterns in several places:
  1882. * Filenames ( Section 4.9)
  1883. * SWITCH case labels ( Section 7.18)
  1884. * The new IF MATCH statement ( Section 7.4)
  1885. * TYPE /MATCH ( Section 1.15)
  1886. * SET FILE TEXT-PATTERNS and BINARY-PATTERNS ( Section 4.3)
  1887. * The \fsearch() and \farraylook() functions (Sections 7.3 and
  1888. 7.10.7)
  1889. * The \fpattern() function used with [M,RE]INPUT ( Section 7.1)
  1890. Patterns are also called wildcards, especially when used for filename
  1891. matching. C-Kermit's pattern syntax is explained in Section 4.9.1,
  1892. and also by the HELP WILDCARDS command.
  1893. 1.20. Multiple Commands on One Line
  1894. As of C-Kermit 7.0, commands can be grouped together on one line by
  1895. separating the commands with commas and enclosing the list in braces.
  1896. For example:
  1897. C-Kermit> { echo One, echo Two, echo Three }
  1898. C-Kermit> do { echo One, echo Two, echo Three }
  1899. Command lists can be nested:
  1900. [ do ] { echo One, echo Two, if true { echo A, echo B}, echo Three }
  1901. and the END command works as it does in macros:
  1902. [ do ] { echo One, echo Two, if true end, echo Three }
  1903. The "one line" stricture is, of course, pliant to line-continuation
  1904. conventions, namely that lines ending in hyphen (-) or left brace ({)
  1905. are to be continued. Thus the first example can also be rendered:
  1906. [ do ] {
  1907. echo One
  1908. echo Two
  1909. echo Three
  1910. }
  1911. (the "do" is optional).
  1912. 1.21. What Do I Have?
  1913. C-Kermit can be built for hundreds of different platforms with
  1914. practically countless configuration options. Certain commands might not
  1915. be available in certain configurations, etc. Even on the same platform,
  1916. different builds are possible: "maximum functionality", "minimum size",
  1917. "maximum performance", and so on. You can find out a lot about the
  1918. configuration of your C-Kermit program with the SHOW FEATURES command.
  1919. Of course, a lot of what it says, especially in the bottom part, might
  1920. seem like gibberish, but can be deciphered with a Rosetta Stone (such
  1921. as the C-Kermit source or theckccfg.txt file). In any case, the
  1922. output from SHOW FEATURES might easily explain why some expected
  1923. feature is missing, or some buffer is smaller than expected. Here's a
  1924. sample of the bottom section for the SunOS version:
  1925. C-Kermit 7.0.196, 1 Jan 2000
  1926. Major optional features included:
  1927. Network support (type SHOW NET for further info)
  1928. Telnet Kermit Option
  1929. Hardware flow control
  1930. External XYZMODEM protocol support
  1931. Latin-1 (West European) character-set translation
  1932. Latin-2 (East European) character-set translation
  1933. Cyrillic (Russian, Ukrainian, etc) character-set translation
  1934. Greek character-set translation
  1935. Hebrew character-set translation
  1936. Japanese character-set translation
  1937. Unicode character-set translation
  1938. Pseudoterminal control
  1939. REDIRECT command
  1940. RESEND command
  1941. Fullscreen file transfer display
  1942. Control-character unprefixing
  1943. Streaming
  1944. Autodownload
  1945. Major optional features not included:
  1946. No Kerberos(TM) authentication
  1947. No SRP(TM) (Secure Remote Password) protocol
  1948. No Secure Sockets Layer (SSL) protocol
  1949. No Transport Layer Security (TLS) protocol
  1950. No encryption
  1951. No X Windows forwarding
  1952. Host info:
  1953. Machine: sun4m
  1954. Model: (unknown)
  1955. OS: SunOS
  1956. OS Release: 4.1.3_U1
  1957. OS Version: 4
  1958. Target: sunos41gsc
  1959. GCC version: 2.7.2
  1960. Compiled Dec 31 1999 10:38:54, options:
  1961. __GNUC__ __STDC__ _POSIX_JOB_CONTROL _SC_JOB_CONTROL ARRAYREFLEN=1024 BIGBUFOK
  1962. BROWSER BSD4 CK_ANSIC CK_APC CK_AUTODL CK_CURSES CK_DNS_SRV CK_ENVIRONMENT
  1963. CK_FAST CK_LOGIN CK_MKDIR CK_NAWS CK_PCT_BAR CK_PERMS CK_RECALL CK_RTSCTS
  1964. CK_SPEED CK_TIMERS CK_TMPDIR CK_TTGWSIZ CK_TTYFD CK_WREFRESH CKEXEC
  1965. CKFLOAT=double CKGHNLHOST ckmaxfiles=64 CKMAXOPEN=64 CKMAXPATH=1023 CKREALPATH
  1966. CKREGEX CKSYSLOG CKTUNING CMDBL=32763 CMDDEP=64 CONGSPD DCMDBUF DIRENT DYNAMIC
  1967. FNFLOAT FORDEPTH=32 GFTIMER HADDRLIST HDBUUCP IFDEBUG IKS_OPTION IKSDB
  1968. IKSDCONF INBUFSIZE=32768 INPBUFSIZ=4096 MAC_MAX=16384 MACLEVEL=128 MAXDDIR=32
  1969. MAXDNUMS=4095 MAXGETPATH=128 MAXTAKE=54 MAXWLD=102400 MSENDMAX=1024 NETCMD
  1970. NETCONN NETPTY NOKVERBS NOSETBUF OBUFSIZE=32768 PARSENSE PATTERNS PIPESEND
  1971. RENAME RLOGCODE SAVEDUID SELECT SIG_V SOL_SOCKET sparc STREAMING sun SUNOS4
  1972. SYSTIMEH TCPSOCKET TIMEH TLOG TNCODE TTLEBUF TTSPDLIST UIDBUFLEN=256 UNIX
  1973. UNPREFIXZERO USE_LSTAT USE_MEMCPY VNAML=4096 WHATAMI XFRCAN Z_MAXCHAN=46
  1974. z_maxchan=46 ZXREWIND
  1975. byte order: big endian
  1976. sizeofs: int=4 long=4 short=2 char=1 char*=4 float=4 double=8
  1977. floating-point: precision=16 rounding=1
  1978. Without going into detail about what all the notation means, notice a
  1979. couple things:
  1980. * The Options section shows symbols ("macros") in effect during
  1981. compilation, together with their values (for those that have
  1982. values). The options are listed in alphabetical order to make any
  1983. particular option easier to find.
  1984. * MAXWLD is the maximum number of files that a wildcard can expand
  1985. to.
  1986. * Anything starting with "NO" is a feature (or something other than a
  1987. feature) that has been deliberately "compiled out", or omitted.
  1988. * Important items for script writers include: CMDBL=32763 (the size
  1989. of the command buffer and therefore the maximum length for a macro
  1990. or variable definition; CMDDEP=64 (the limit on recursion depth);
  1991. FORDEPTH=32 (the nesting limit on FOR loops); INBUFSIZE=32768 (the
  1992. size of the INPUT command circular buffer); MAC_MAX=16384 (the
  1993. maximum number of macros), etc.
  1994. See theckccfg.txt file for details.
  1995. 1.22. Generalized File Input and Output
  1996. C-Kermit 7.0 adds a new generalized I/O system for stream files,
  1997. augmenting (and to some extent, overlapping with) the older OPEN, READ,
  1998. WRITE, and CLOSE commands. In the new file i/o system, which can be
  1999. used simultaneously with the old one, all commands are grouped together
  2000. under the new FILE keyword, and some related functions and variables
  2001. are added.
  2002. 1.22.1. Why Another I/O System?
  2003. The well-known LOG, OPEN, READ, WRITE, and CLOSE commands have the
  2004. following restrictions:
  2005. 1. Only one READ file and one WRITE file can be open at a time.
  2006. 2. The READ and WRITE commands are strictly line oriented.
  2007. 3. These commands can not be used with binary files.
  2008. 4. They do not support read/write access or random access.
  2009. 5. The syntax is a bit counterintuitive for programmers.
  2010. The new file i/o system allows multiple files to be open at once, in
  2011. any desired combination of modes (read/write/append) supported by the
  2012. operating system, for line, block (record), or character i/o, for
  2013. sequential or random access, using consistent syntax and conventions.
  2014. The new system, however, does not replace the old one, since the old
  2015. system still must be used for:
  2016. 1. The session, packet, debug, transaction, and connection logs.
  2017. 2. Reading and writing commands rather than files.
  2018. 3. Existing scripts.
  2019. The new system works only with regular files, not with commands or
  2020. pipes or mailboxes or pseudoterminals. No special provisions are made
  2021. in the FILE commands for handling devices or network connections, nor
  2022. for preventing you from trying to open them; if the underlying
  2023. operating system treats them like regular stream disk files, the FILE
  2024. commands (except, of course SEEK, REWIND, and COUNT) might work with
  2025. them. (In C programming terms, the FILE commands are, at present,
  2026. nothing more than a front end to fopen() / fread() / fwrite() /
  2027. fclose() and friends, which are a portable API to sequential files, but
  2028. this might change in the future for platforms like VMS and VOS that
  2029. have more complicated file systems.)
  2030. Definitions:
  2031. Channel
  2032. A number assigned to a file when it is opened, by which it must
  2033. be referred to in all input/output operations.
  2034. Read/Write Pointer
  2035. The current position in an open file, expressed as the 0-based
  2036. byte count from the beginning.
  2037. 1.22.2. The FILE Command
  2038. FILE keyword [ switches ] channel [ data ]
  2039. The keyword specifies the function: FILE OPEN, FILE READ, FILE
  2040. WRITE, FILE CLOSE, etc. For convenience (and for familiarity to
  2041. C programmers), the two-word FILE commands can be shortened to
  2042. the single words FOPEN, FREAD, FWRITE, FCLOSE, and so on.
  2043. Switches are optional, and modify or amplify the requested file
  2044. function.
  2045. As in C, Fortran, and other programming languages, open files are
  2046. referred to by "channels", integers such as 0, 1, 2, 3, and so on. A
  2047. channel number is assigned when you open a file. The number of
  2048. available channels depends on the underlying operating system, and can
  2049. be seen in the variable:
  2050. \v(f_max)
  2051. or by giving the FILE LIST (FLIST) command. Channels are discussed in
  2052. greater detail in Section 1.22.4.
  2053. FILE command errors can be caught with IF FAIL after the FILE command.
  2054. In addition, the \v(f_error) variable is set to the completion code of
  2055. the command: 0 if no error, or a negative number if there was an error.
  2056. The error codes are listed in Section 1.22.5.
  2057. The command to open a file is:
  2058. FILE OPEN [ switches ] variable filename
  2059. Opens a file for the type of access specified by the switches,
  2060. or for read-only access if no switches are given. Upon success,
  2061. a channel number is assigned to this file and stored in the
  2062. given variable so you can refer to the open file in subsequent
  2063. i/o commands. If the file can not be opened, the FILE OPEN
  2064. command fails. Synonym: FOPEN.
  2065. The FILE OPEN switches are:
  2066. /READ
  2067. Open the file for read access. If no switches are given, /READ
  2068. is assumed. If the file does not exist or can't be opened for
  2069. read access, the FILE OPEN command fails.
  2070. /WRITE
  2071. Allow writing. If a file of the same name already exists, it is
  2072. overwritten unless /READ or /APPEND is also included. If a file
  2073. of the given name does not exist, it is created.
  2074. /APPEND
  2075. Equivalent to /WRITE, except that if the file exists, it is not
  2076. destroyed. The read/write pointer is set to the end of the file,
  2077. so unless you change it with FILE SEEK or REWIND (see below),
  2078. the first FILE WRITE command adds to the end of the file,
  2079. preserving what was there already. If /WRITE is also given, it
  2080. is ignored.
  2081. /BINARY
  2082. Open the file in "binary" mode, rather than text mode. This
  2083. switch is meaningless (but still can be used) in UNIX. In VMS,
  2084. Windows, and OS/2, it inhibits end-of-line processing and
  2085. conversion, and so should be used for binary files and/or files
  2086. that are to be accessed in record or character mode rather than
  2087. line by line.
  2088. The variable for the channel number can be any kind of variable: the
  2089. \%x kind, a macro name, or an array element. But it must be a variable,
  2090. not a number -- C-Kermit assigns the channel number; you can't tell it
  2091. what number to use.
  2092. Example:
  2093. FILE OPEN \%c oofa.txt ; Open oofa.txt for reading.
  2094. IF FAIL exit 1 Can't open oofa.txt ; Always check to see if it worked.
  2095. ECHO oofa.txt: channel = \%c
  2096. If the file oofa.txt is opened successfully, a channel number is
  2097. assigned to the variable \%c. Here's another example using a macro name
  2098. for the channel number:
  2099. FILE OPEN channel oofa.txt ; Open oofa.txt for reading.
  2100. IF SUCCESS ECHO oofa.txt: channel = \m(channel)
  2101. Switches can be combined when it makes sense and the underlying
  2102. operating system allows it. For example, to open a file in binary mode
  2103. for reading and writing (sometimes called "update"):
  2104. FILE OPEN /READ /WRITE /BINARY \%c budget.db
  2105. Some combinations might be allowed, others not. For example /READ
  2106. /APPEND will usually not be allowed. /WRITE /APPEND is treated as
  2107. /APPEND.
  2108. A major advantage of the new system over the older one is that you can
  2109. have multiple files open at once. Suppose, for example, that you want
  2110. to open all the files in a certain directory at once:
  2111. .\%n := \ffiles(/usr/olga*,&f) ; Get file list into array.
  2112. if ( > \%n \v(f_max) ) { ; Make sure there aren't too many.
  2113. exit 1 {\v(dir): \%n = Too many files}
  2114. }
  2115. declare \&c[\%n] ; Make array for channel numbers.
  2116. for \%i 1 \%n 1 { ; Loop to open every file...
  2117. file open \&c[\%i] \&f[\%i] ; Try to open this one
  2118. if fail exit 1 Open error: \&f[\%i] ; Check for failure
  2119. }
  2120. If this loop completes successfully, the \&c[] array will contain \%n
  2121. channel numbers of open files in elements 1 through \%n.
  2122. Any file that you open with FILE OPEN stays open until Kermit exits, or
  2123. you close it explicitly. The command to close a file is:
  2124. FILE CLOSE { ALL, channel }
  2125. If a channel number is given and the channel refers to an open
  2126. file, the file is closed and the channel is freed for reuse; if
  2127. the channel does not refer to an open file, an error message is
  2128. printed and the command fails. If ALL is specified instead of a
  2129. specific channel, all files opened with FILE OPEN are closed and
  2130. if all open files were closed successfully (even if no files
  2131. were open), the command succeeds; if any open file could not be
  2132. closed, the command fails; however, all open files that could be
  2133. closed are still closed. Synonym: FCLOSE.
  2134. FILE CLOSE might fail because, for example, the disk filled up or a
  2135. quota was exceeded. Example:
  2136. fopen /write \%c new.txt ; Open new.txt for writing.
  2137. if fail exit 1 ; Check for error.
  2138. fclose \%c ; Close the file we just opened.
  2139. This creates a 0-length file called new.txt.
  2140. Note that FILE OPEN /WRITE (without /READ or /APPEND) always creates a
  2141. new file, and therefore destroys any file with the same name that might
  2142. already exist (assuming you have permission to delete it). To avoid
  2143. overwriting existing files, simply check first:
  2144. if exist new.txt exit 1 {Fatal - new.txt already exists}
  2145. fopen /write \%c new.txt
  2146. if fail ...
  2147. The next two commands give information about open files:
  2148. FILE STATUS channel
  2149. Tells the name of the file, if any, open on the given channel
  2150. and the switches it was opened with. The read/write pointer is
  2151. also shown; this is where the next read or write will occur;
  2152. "[EOF]" is shown if the current position in the open file is the
  2153. end -- i.e. the next read will fail if the file was opened in
  2154. /READ mode; the next write will add material to the end. The
  2155. current line number (0-based) is also shown if known. The FILE
  2156. STATUS command succeeds if the channel is open, and fails if
  2157. there is no open file on the given channel, or if the channel
  2158. number is invalid or out of range. Synonym: FSTATUS.
  2159. FILE LIST
  2160. Lists the channel number and name of each open file, along with
  2161. its OPEN modes (R, W, A, B, RW, etc) and its current read/write
  2162. pointer or "[EOF]" if it is at the end. Also tells the number of
  2163. files currently opened with FILE OPEN, plus the maximum number
  2164. of open files allowed by the system and the maximum number
  2165. allowed for FILE OPEN. Synonym: FLIST.
  2166. Next come the commands for reading and writing files:
  2167. FILE READ [ switches ] channel [ variable ]
  2168. Reads data from the file on the given channel number into the
  2169. variable, if one was given; if no variable was given, the result
  2170. is printed on the screen. IMPORTANT: The variable should
  2171. normally be a macro name rather than a \%x or \&x[] variable if
  2172. you want backslash characters in the file to be taken literally
  2173. (see pp.408-412 ofUsing C-Kermit for an explanation; you
  2174. can also read into a \%x or \&x[] variable, but then you must
  2175. remember to protect future references to by \fcontents() if you
  2176. don't want C-Kermit to process any backslashes it might
  2177. contain). The desired amount of data (according to the switches)
  2178. is read from the file at the current read/write pointer, and
  2179. upon completion the read/write position is updated to first byte
  2180. after the data that was read, no matter what switches were
  2181. given. Synonym: FREAD.
  2182. FILE WRITE [ switches ] channel text
  2183. Writes the given text to the file on the given channel number.
  2184. The text, of course, can be literal text or a variable, or any
  2185. combination. If the text might contain leading or trailing
  2186. spaces, it must be enclosed in braces if you want to preserve
  2187. them. Synonym: FWRITE.
  2188. Before proceeding, a caution about the NUL character. C-Kermit is so
  2189. named because it is a Kermit program written in the C language. In C,
  2190. character strings are represented as a sequence of non-NUL bytes
  2191. terminated by a NUL byte (a byte in which all bits are 0). Thus a C
  2192. string can not contain NUL bytes; it always ends with the first NUL
  2193. byte. C-Kermit variables are implemented as C strings and therefore
  2194. can't contain NUL bytes either, so the FILE READ and FILE WRITE
  2195. commands do not handle files or strings that contain NUL bytes, except
  2196. when the /CHARACTER switch is included with the FILE READ or WRITE
  2197. command, or when /LPAD:0 or /RPAD:0 is given with the FILE WRITE
  2198. command; these switches are explained below.
  2199. Also note that Kermit can not be used read or write binary numbers in
  2200. the machine's internal format (integer or floating-point); in general,
  2201. numbers can be processed only when represented as numeric or
  2202. floating-point strings.
  2203. FILE READ switches are:
  2204. /LINE
  2205. Specifies that a line of text is to be read. A line is defined
  2206. according to the underlying operating system's text-file format.
  2207. For example, in UNIX a line is a sequence of characters up to
  2208. and including a linefeed, or the end of the file, which ever
  2209. comes first. The line terminator (if any) is removed before
  2210. assigning the text to the variable. If no switches are included
  2211. with the FILE READ command, /LINE is assumed. Normally this
  2212. switch should not be used with files opened in /BINARY mode (but
  2213. nothing prevents it either).
  2214. /SIZE:number
  2215. Specifies that the given number of bytes (characters) is to be
  2216. read. The actual number of bytes returned will be less if the
  2217. end of file is reached (or a NUL byte is encountered). For
  2218. example, if a file is 514 bytes long, FILE READ /SIZE:512
  2219. returns 512 bytes the first time and 2 bytes the second time.
  2220. FILE READ /SIZE provides a kind of "record i/o" for files that
  2221. do not necessarily contain lines. The resulting block of
  2222. characters is assigned to the variable without any editing.
  2223. Synonym: /BLOCK.
  2224. /CHARACTER
  2225. Equivalent to /SIZE:1. If FILE READ /CHAR succeeds but the
  2226. variable is empty, this indicates a NUL byte was read. Synonym:
  2227. BYTE.
  2228. FILE WRITE switches are:
  2229. /LINE
  2230. Specifies that an appropriate line terminator is to be added to
  2231. the end of the text. If no switches are included, /LINE is
  2232. assumed.
  2233. /SIZE:number
  2234. Specifies that the given number of bytes (characters) is to be
  2235. written. If the given text is longer than the requested size, it
  2236. is truncated; if is shorter, it is padded according /LPAD and
  2237. /RPAD switches. Synonym: /BLOCK.
  2238. /LPAD[:value]
  2239. If /SIZE was given, but the text is shorter than the requested
  2240. size, the text is padded on the left with sufficient copies of
  2241. the character whose ASCII value is given to write the given
  2242. length. If no value is specified, 32 (the code for Space) is
  2243. used. The value can also be 0 to write the indicated number of
  2244. NUL bytes. If /SIZE was not given, this switch is ignored.
  2245. /RPAD[:value]
  2246. Like LPAD, but pads on the right.
  2247. /CHARACTER
  2248. Specifies that one character should be written. If the text is
  2249. empty or not given, a NUL character is written; otherwise the
  2250. first character of text is given. Synonym: /BYTE.
  2251. /STRING
  2252. Specifies that the text is to be written as-is, with no
  2253. terminator added.
  2254. Here's an example in which we copy a text file line by line:
  2255. file open /read \%c oofa.txt ; Open input file
  2256. if fail exit 1 Can't open input file ; Check that it's open
  2257. file open /write \%d new.txt ; Open output file
  2258. if fail exit 1 Can't open output file ; Check
  2259. while true { ; Loop to copy lines
  2260. file read /line \%c line ; Read a line
  2261. if fail break ; Assume failure = end of file
  2262. file write /line \%d {\m(line)} ; Write the line to output file
  2263. if fail exit 1 Write failure ; Failure here is fatal
  2264. }
  2265. file close \%c ; Close the two files
  2266. file close \%d
  2267. Note that since /LINE is the default for both FILE READ and FILE WRITE,
  2268. it can be omitted as in the following example, where we also use the
  2269. short names for the FILE commands.
  2270. fopen /read \%c oofa.txt ; Open input file
  2271. if fail exit 1 Can't open input file ; Check that it's open
  2272. fopen /write \%d new.txt ; Open output file
  2273. if fail exit 1 Can't open output file ; Check
  2274. while true { ; Loop to copy lines
  2275. fread \%c line ; Read a line
  2276. if fail break ; Assume failure = end of file
  2277. fwrite \%d {\m(line)} ; Write the line to output file
  2278. if fail exit 1 Write failure ; Failure here is fatal
  2279. }
  2280. fclose \%c ; Close the two files
  2281. fclose \%d
  2282. Here's the same example using "record i/o" (the open and close
  2283. sequences are are omitted since they are the same as above). The result
  2284. is the same, but execution is much faster:
  2285. while true { ; Loop to copy blocks
  2286. fread /size:512 \%c block ; Read a block into \%a
  2287. if fail break ; Assume failure = end of file
  2288. fwrite /string \%d {\m(block)} ; Write the block to output file
  2289. if fail exit 1 Write failure ; Failure here is fatal
  2290. }
  2291. Although record i/o is faster, it should not be used in line-oriented
  2292. applications, since it returns arbitrary chunks of the file to your
  2293. script, rather than lines. In this example, FWRITE /STRING is used
  2294. rather than FWRITE /SIZE:512 to avoid the last output block being
  2295. padded beyond the original file's length.
  2296. A file can also be copied character by character, but this is much
  2297. slower than line i/o and VERY much slower than block i/o:
  2298. while true { ; Loop to copy blocks
  2299. fread /char \%c c ; Read a character into c
  2300. if fail break ; Assume failure = end of file
  2301. fwrite /char \%d {\m(c)} ; Write character to output file
  2302. if fail exit 1 Write failure ; Failure is fatal
  2303. }
  2304. Although character i/o is slow, it is the only way to process files
  2305. that contain NUL characters (i.e. bytes composed of only zero bits). In
  2306. the example above, when "fread /char \%c c" returns a NUL, the c
  2307. variable is empty. But since the FREAD /CHAR command did not fail, we
  2308. know the result was really a NUL. FWRITE /CHAR, when given an empty
  2309. variable (or no variable at all) writes a NUL. Thus the loop above will
  2310. copy any file at all (very slowly). In non-copying applications, NULs
  2311. are detected like this:
  2312. fread /char \%c c
  2313. if fail (do something)
  2314. if not def c (a NUL byte was read)
  2315. Finally some advanced file operations:
  2316. FILE FLUSH channel
  2317. For output files only: commits all previous writes to disk, in
  2318. case the computer was buffering them. Synonym: FFLUSH.
  2319. FILE COUNT [ { /BYTES, /LINES, /LIST, /NOLIST } ] channel
  2320. By default, or if the /BYTES switch is given, counts the bytes
  2321. in the file, if any, open on the given channel. If the /LINES
  2322. switch is given, counts lines in the file. If the /LIST switch
  2323. is given, the result is printed. If the /NOLIST switch is given,
  2324. the result is not printed. /QUIET is a synonym for /NOLIST. If
  2325. neither /LIST nor /NOLIST is given, the result is printed if the
  2326. command is given at top level, i.e. not from a command file or
  2327. macro. In all cases, the result of the most recent FILE COUNT
  2328. command is stored in the variable \v(f_count). Note that FILE
  2329. COUNT /LINE works (and can only work) by reading the entire
  2330. file; expect it to take some time if the file is large. Synonym:
  2331. FCOUNT.
  2332. FILE REWIND channel
  2333. Moves the read/write pointer to the beginning of the file.
  2334. Equivalent to FILE SEEK channel 0. Synonym: FREWIND.
  2335. FILE SEEK [ switches ] channel { [{+,-}]number, LAST, EOF }
  2336. Moves the read/write pointer for the file on this channel to the
  2337. given position, which may be a byte (character) number or a line
  2338. number, expressed in either absolute or relative terms.
  2339. Switches:
  2340. /BYTE
  2341. The number given is a byte number. Synonym: /CHARACTER.
  2342. /LINE
  2343. The number given is a line number.
  2344. /ABSOLUTE
  2345. The number given is absolute.
  2346. /RELATIVE
  2347. The number given is relative to the current position.
  2348. By default, or if the /BYTE switch is given, the number is a
  2349. byte number (0 = first byte). If /LINE is given, the number is a
  2350. line number (0 = first line). EOF means to move to the end of
  2351. the file. LAST means to move to the last line or character of
  2352. the file, depending on whether it's a line or character seek.
  2353. If neither the /RELATIVE nor the /ABSOLUTE switch is given, then
  2354. if a signed number is given, the motion is relative to the
  2355. current position. An expression that evaluates to a negative
  2356. number is not considered signed for this purpose; that is, a
  2357. sign (+ or -) must be included as the first character of the
  2358. number in the command itself to force a relative seek (in the
  2359. absence of /RELATIVE or /ABSOLUTE).
  2360. If the number has no sign, or if the /ABSOLUTE switch is given,
  2361. the number represents an absolute position (relative to the
  2362. beginning of the file). Subsequent FILE READs or WRITEs will
  2363. take place at the new position.
  2364. If the read/write pointer is placed after the end of the file, a
  2365. subsequent FILE READ will fail, but a FILE WRITE will succeed
  2366. (possibly creating a file with "holes"). If a FILE SEEK /BYTE
  2367. command is given, the current line becomes unknown (unless the
  2368. position is 0) and subsequent FILE SEEK /RELATIVE /LINE commands
  2369. will fail until the next non-relative FILE SEEK /LINE command is
  2370. given. Synonym: FSEEK.
  2371. An absolute FILE SEEK to a negative position fails silently, as does a
  2372. relative seek to a position before the beginning of the file.
  2373. A caution about relative SEEKs: remember that the number is relative to
  2374. the current position. Whenever you read or write, this changes the
  2375. position. In each of the following examples, assume the file open on
  2376. channel \%c is positioned at line n (the FREAD target variable is
  2377. omitted for lack of space):
  2378. { FREAD \%c, FSEEK /LINE \%c -1, FREAD \%c } <-- Reads line n twice
  2379. { FREAD \%c, FSEEK /LINE \%c +0, FREAD \%c } <-- Reads lines n and n+1
  2380. { FREAD \%c, FSEEK /LINE \%c +1, FREAD \%c } <-- Reads lines n and n+2
  2381. { FREAD \%c, FSEEK /LINE \%c -2, FREAD \%c } <-- Reads lines n and n-1
  2382. { FREAD \%c, FSEEK /LINE \%c -3, FREAD \%c } <-- Reads lines n and n-2
  2383. Another caution: Using FSEEK and FREAD /SIZE to repeatedly read the
  2384. same disk block (e.g. when sampling a database record that is
  2385. frequently updated) might not give you updated disk blocks due to the
  2386. internal buffering and caching of the C library (this probably varies
  2387. from one platform/compiler combination to another). If necessary you
  2388. can force a fresh disk read with a close/open sequence:
  2389. FCLOS \%c
  2390. FOPEN \%c samefilename
  2391. FSEEK \%c samespot
  2392. FREAD /SIZE:howmanybytes \%c variable
  2393. 1.22.3. FILE Command Examples
  2394. To read the last 10 lines of a text file into an array:
  2395. fopen /read \%c oofa.txt ; Open the file
  2396. if fail exit 1 Can't open oofa.txt ; Always check for failure
  2397. dcl \&a[10] ; Declare a 10-element array
  2398. fcount /line \%c ; Count lines in the file
  2399. fseek /line \%c \v(f_count)-10 ; Seek to 10 lines from the end
  2400. if fail exit 1 Can't seek ; Check for failure
  2401. for \%i 1 10 1 { fread \%c \&a[\%i] } ; Read the last 10 lines
  2402. fclose \%c ; Close the file
  2403. Note that blank lines show up as empty (undefined) array elements, for
  2404. example if you give a "show array a" command at this point. This is
  2405. normal. You can still use these elements; e.g.:
  2406. for \%i 1 10 1 { echo \%i. \&a[\%i] } ; Display the 10 lines
  2407. Here is how to read the last line of a file (already open on channel
  2408. \%c):
  2409. fseek /line \%c last ; Seek directly to last line
  2410. Alternatively:
  2411. fseek /line \%c eof ; Seek to end of file
  2412. fseek /line \%c -1 ; Seek to beginning of last line
  2413. Alternatively:
  2414. fcount /line \%c ; Count the file's lines
  2415. fseek /line \%c \v(f_count)-1 ; Seek to last line
  2416. fread \%c ; Read it
  2417. To read every other line from the file (using relative SEEK), skipping
  2418. the first line:
  2419. fopen /read \%c oofa.txt ; Open the file
  2420. while ( success ) { ; Loop through lines
  2421. fseek /line \%c +1 ; Skip a line
  2422. if success fread \%c ; Read & display a line
  2423. }
  2424. fclose \%c ; Close the file
  2425. Here is how to read the lines of a file in reverse order:
  2426. fopen /read \%c oofa.txt ; Open
  2427. if fail exit 1 ; Check
  2428. fseek /line \%c last ; Seek to last line
  2429. while success { ; Loop
  2430. fread \%c ; Read line
  2431. fseek /line \%c -2 ; Seek backwards two lines
  2432. }
  2433. fclose \%c ; Close the file
  2434. The loop works because a relative SEEK outside the file fails.
  2435. It is also possible to use block i/o to manage random-access files with
  2436. fixed-length records (as long as they don't contain NUL characters).
  2437. Suppose, for example, you have a file of "card image" records with
  2438. fixed-field information about customers, such as:
  2439. Name: Columns 1-32 (column numbers are 1-based)
  2440. Address: Columns 33-72
  2441. Balance: Columns 73-80
  2442. The records are indexed by customer number, starting with 0. There are
  2443. no line terminators separating them. Therefore the record for customer
  2444. number n starts at position nx 80 (\%n*80).
  2445. Now suppose we received a payment from customer number 173 and want to
  2446. update the balance:
  2447. .\%n = 173 ; Customer (record) number
  2448. .\%a = 12.72 ; Amount
  2449. fopen /read /write \%c customer.db ; Open the file
  2450. if fail stop 1 OPEN FAILED: \f_errmsg() ; Check
  2451. fseek /byte \%c 80*\%n ; Seek to record
  2452. fread /size:80 \%c r ; Read the record
  2453. if fail stop 1 READ FAILED: \f_errmsg() ; Check (IMPORTANT)
  2454. .\%b := \fright(\m(r),8) ; Extract the balance
  2455. .\%b := \ffpadd(\%b,\%a,2) ; Add the new payment
  2456. if fail stop 1 ARITHMETIC ERROR: \%b/\%a ; Catch bad records
  2457. .r := {\fleft(\m(r),72)\flpad(\%b,8)} ; Update the record
  2458. fseek /byte \%c 80*\%n ; Reposition to same spot
  2459. fwrite /size:80 \%c {\m(r)} ; Replace the record
  2460. if fail stop 1 WRITE FAILED: \f_errmsg() ; Check
  2461. fclose \%c ; Close the file
  2462. REMEMBER: Using FILE SEEK to move beyond the end of file can result in
  2463. a file with holes when writing; when reading, an end-of-file error will
  2464. occur -- be sure to check for it.
  2465. 1.22.4. Channel Numbers
  2466. C-Kermit's channel numbers are integers from 0 to some
  2467. platform-dependent limit, such as 46 or 1985 (the value of \v(f_max)).
  2468. This is the limit placed by the operating system on the number of files
  2469. that may be opened by one process or user or job, minus the standard
  2470. input, output, and error files, and minus the number of files reserved
  2471. by C-Kermit for logs, OPEN READ and WRITE, and file transfer (and maybe
  2472. some command files -- the \v(f_max) number can't be exact).
  2473. Although you must include a variable in the FILE OPEN command, to which
  2474. the channel number is assigned, you don't have to use a variable in the
  2475. other FILE commands if you know what the number is -- you can just put
  2476. the number. This saves you a few keystrokes when typing commands at the
  2477. prompt:
  2478. fopen \%c oofa.txt
  2479. flist
  2480. 0. /usr/olga.oofa.txt (R) 0
  2481. This tells the channel number is 0 (the number on the left is the
  2482. channel file's channel number). Of course you can also find it by
  2483. echoing the variable:
  2484. echo \%c
  2485. 0
  2486. Or with "fstatus \%c". Now you can type commands like:
  2487. fread 0
  2488. to read a line from the file. Obviously, however, using digits rather
  2489. than a variable for the channel number would be poor practice in a
  2490. script.
  2491. If in commands like:
  2492. fread \%c \%a
  2493. you have trouble remembering which variable is which, note that the
  2494. channel number is, indeed, a number. Anywhere C-Kermit accepts a number
  2495. it can also accept an expression, so you can put parentheses around the
  2496. channel number to remind you it's the channel number and not the
  2497. variable into which data is to be read:
  2498. fread (\%c) \%a
  2499. Normally channel numbers are assigned sequentially as 0, 1, 2, ... up
  2500. to the limit. However, once you start closing files, there can be holes
  2501. in the sequence. New channels are assigned to fill in the holes. Thus
  2502. you can't depend on channel numbers being in any particular sequence.
  2503. 1.22.5. FILE Command Errors
  2504. Each FILE command sets the variable \v(f_error) to one of the following
  2505. values:
  2506. 0 = No error
  2507. -1 = System error
  2508. -2 = Attempt to read after end of file
  2509. -3 = Channel not open
  2510. -4 = Channel number out of range (negative or too large)
  2511. -5 = Numeric argument (size, ...) out of range
  2512. -6 = File not found
  2513. -7 = Bad or missing filename
  2514. -8 = Too many files are already open (FILE OPEN only)
  2515. -9 = Forbidden operation (e.g. write to a read-only file)
  2516. -10 = Access denied
  2517. -11 = Illegal combination of OPEN modes (FILE OPEN only)
  2518. -12 = Buffer overflow
  2519. -13 = Current line number unknown (for relative line seeks)
  2520. -14 through -98: Reserved.
  2521. -99 = Requested operation not implemented in this version of C-Kermit
  2522. -999 = Unknown error
  2523. When \v(f_error) is -1, this means the FILE command failed because
  2524. because of a system error, in which case you can examine the following
  2525. variables:
  2526. \v(errno) = System error number.
  2527. \v(errstring) = Error message corresponding to \v(errno).
  2528. A special function is available for translating the \v(f_error) code to
  2529. an error message string:
  2530. \f_errmsg([code])
  2531. If the code is -1, returns error message of the most recent system
  2532. error; otherwise if the code is a valid \v(f_error) value, the associated
  2533. message is returned. If the code is omitted, the status message
  2534. corresponding to the current \v(f_error) value is returned.
  2535. A FILE command that fails prints the appropriate error message
  2536. automatically, except when the command is READ or SEEK and the error is
  2537. -2 (end of file); in that case, the command still fails, but does not
  2538. print a message. This allows constructions such as:
  2539. fopen \%c oofa.txt
  2540. while success { fread \%c }
  2541. fclose \%c
  2542. to work as expected, i.e. without an annoying message when the end of
  2543. file is reached.
  2544. 1.22.6. File I/O Variables
  2545. The variables associated with the file i/o package are:
  2546. \v(f_count)
  2547. Result of the most recent FILE COUNT (FCOUNT) command.
  2548. \v(f_error)
  2549. Numeric error code of most recent FILE command (0 = no error).
  2550. \v(f_max)
  2551. Maximum number of files open simultaneously.
  2552. 1.22.7. File I/O Functions
  2553. Some of the FILE commands can also be issued as function calls, which
  2554. makes script writing a bit more convenient, especially for C
  2555. programmers. Also, several functions are provided that do not have
  2556. command equivalents. Each of these functions takes a channel number as
  2557. the first argument. These functions do not work for OPEN { READ, !READ,
  2558. WRITE, !WRITE, and APPEND } files.
  2559. \f_status(channel)
  2560. Returns 0 if the channel is not open, otherwise a number between
  2561. 1 and 15 which is the sum of the OPEN modes:
  2562. 1 = /READ
  2563. 2 = /WRITE
  2564. 4 = /APPEND
  2565. 8 = /BINARY
  2566. The remaining functions work only for open channels. Each of these
  2567. functions can fail for the applicable reasons listed inSection
  2568. 1.22.5. For instructions on handling function errors, seeSection
  2569. 7.12.
  2570. \f_pos(channel)
  2571. Returns the file's current read/write pointer (0-based). There
  2572. is no FILE command equivalent.
  2573. \f_line(channel)
  2574. Returns the file's current line number (0-based), if known,
  2575. otherwise -1. There is no FILE command equivalent. The line
  2576. number is known as long as no character or block i/o has been
  2577. done on the channel.
  2578. \f_handle(channel)
  2579. Returns the "file handle" of the file. That is, it translates
  2580. the portable C-Kermit channel number into a system-specific file
  2581. handle or number that can be passed to other programs on the
  2582. same platform. In UNIX this is a file descriptor. There is no
  2583. FILE command equivalent.
  2584. \f_eof(channel)
  2585. Returns 1 if the read/write pointer of the file on the given
  2586. channel is at the end of the file, 0 otherwise. Convenient in
  2587. WHILE statements, e.g.:
  2588. while not \f_eof(\%c) { fread \%c }
  2589. \f_getchar(channel)
  2590. Equivalent to FREAD /CHAR. Returns the character actually read.
  2591. If \f_getchar() does not fail but the return value is empty,
  2592. this means a NULL character was read.
  2593. \f_getline(channel)
  2594. Equivalent to FREAD /LINE. Returns the line actually read, but
  2595. with the line terminator stripped. If \f_getline() does not fail
  2596. but the return value is empty, this normally means an empty line
  2597. was read.
  2598. \f_getblock(channel,n)
  2599. Equivalent to FREAD /SIZE:n. Returns the block of characters
  2600. actually read. If the returned block is smaller than n, it
  2601. indicates either that the end of file was reached or a NUL
  2602. character is in the block.
  2603. \f_putchar(channel,c)
  2604. Equivalent to FWRITE /CHARACTER. Writes the character c. If c
  2605. contains more than one character, only the first is written. If
  2606. c is empty a NUL is written. Returns the number of characters
  2607. written on success, or a negative error code upon failure.
  2608. \f_putline(channel,string)
  2609. Equivalent to FWRITE /LINE. Writes the string and adds the
  2610. appropriate line termination character or sequence. If the
  2611. string is empty or omitted, an empty line is written. Returns
  2612. the number of characters written on success, or a negative error
  2613. code upon failure.
  2614. \f_putblock(channel,string)
  2615. Equivalent to FWRITE /STRING. Writes the string as given. If the
  2616. string is empty or omitted, nothing is written. Returns the
  2617. number of characters written on success, or a negative error
  2618. code upon failure.
  2619. 1.22.8. File I/O Function Examples
  2620. fopen /read \%c oofa.txt ; Open our favorite file for reading
  2621. if failure exit 1 ; Check that it's open
  2622. while not \f_eof(\%c) { ; Loop until EOF
  2623. .line := \f_getline(\%c) ; Get a line
  2624. if success echo {\m(line)} ; Echo it
  2625. }
  2626. if not \f_eof(\%c) { ; Check reason for loop exit
  2627. exit 1 File Error: \f_errmsg() ; If not EOF say so.
  2628. }
  2629. frewind \%c ; Rewind the file
  2630. while not \f_eof(\%c) { ; Same thing but with block i/o
  2631. .block := \f_getblock(\%c,256) ; (much faster than line i/o)
  2632. if success xecho {\m(block)}
  2633. }
  2634. frewind \%c ; Rewind again
  2635. while not \f_eof(\%c) { ; Same deal but with character i/o
  2636. .c := \f_getchar(\%c) ; (much slower than line i/o)
  2637. if success xecho {\m(c)}
  2638. }
  2639. close \%c
  2640. To close all open files (equivalent to FCLOSE ALL):
  2641. for \%i 0 \v(f_max)-1 1 {
  2642. if \f_status(\%i) fclose \%i
  2643. }
  2644. 1.23. The EXEC Command
  2645. The EXEC command is available only in UNIX.
  2646. EXEC [ /REDIRECT ] command [ arg1 [ arg2 [ ... ] ]
  2647. Runs the given command with the arguments in such a way that the
  2648. command replaces C-Kermit in memory, and C-Kermit ceases to
  2649. execute. EXEC is like RUN, except instead of returning to
  2650. C-Kermit when finished, the command returns to whatever process
  2651. invoked Kermit.
  2652. In the normal case, no files are closed, so the EXEC'd command inherits
  2653. the open files, read/write pointers, working directory, process ID,
  2654. user ID (unless command is SUID), group ID (unless command is SGID),
  2655. groups, etc. (In UNIX, the EXEC command is simply a front end for
  2656. execvp().)
  2657. If the /REDIRECT switch is included, then if a connection is open (SET
  2658. LINE or SET HOST), it becomes the standard input and output of the
  2659. EXEC'd program. If no connection is open, the /REDIRECT switch has no
  2660. effect. For example to use C-Kermit for PPP dialing in Linux:
  2661. set modem type usr ; Specify the kind of modem you have
  2662. set line /dev/ttyS1 ; Specify the device it's connected to
  2663. set speed 57600 ; and the speed
  2664. set flow rts/cts ; and flow control.
  2665. set dial retries 100 ; Try the dial sequence up to 100 times.
  2666. dial {{9-212-555-1212}{9-212-555-1213}{9-212-555-1214}{9-212-555-1215}}
  2667. if fail exit 1
  2668. for \%i 1 16 1 { ; Try up to 16 times to get login prompt
  2669. input 10 Login: ; Wait 10 sec for it to appear
  2670. if success break ; Got it - proceed...
  2671. output \13 ; Send a carriage return and try again
  2672. }
  2673. if ( > \%i 16 ) stop 1 NO LOGIN PROMPT
  2674. lineout \(myuserid) ; Send user ID
  2675. input 30 assword: ; Wait for Password prompt
  2676. if fail stop 1 NO PASSWORD PROMPT
  2677. lineout \m(mypassword) ; Send the password.
  2678. exec /redirect pppd ; Replace ourselves with pppd.
  2679. In this example we assume that the script has already set up the
  2680. myuserid and mypassword variables -- normally the password should be
  2681. prompted for, rather than stored on disk. Notice the advantages over
  2682. the well-known "chat script":
  2683. * You don't have to control the modem itself with AT commands;
  2684. Kermit's DIAL command does this for you.
  2685. * You can have Kermit automatically redial as many times as you want
  2686. until it gets a connection (if this is legal in your country).
  2687. * You can have Kermit fetch the number or numbers from a dialing
  2688. directory.
  2689. * You can have Kermit cycle through a list of phone numbers (this is
  2690. new in C-Kermit 7.0; see Section 2.1.16) without having to
  2691. enter the numbers in a dialing directory.
  2692. * Dialing is location-independent; you can use the same script to
  2693. dial from different areas or countries.
  2694. * Once the connection is made, the full power of Kermit's script
  2695. language is available to manage the dialog with the terminal server
  2696. or other device that answers the phone call.
  2697. NOTE: PPP and SLIP dialing are not available in Windows 95/98/NT/2000,
  2698. whose APIs do not provide a method for an application to hand over a
  2699. connection to the PPP or SLIP driver.
  2700. 1.24. Getting Keyword Lists with '?'
  2701. Suppose you type "te" at the C-Kermit> 6.0 prompt and then Esc or Tab
  2702. to request keyword completion. Kermit beeps, indicating that more than
  2703. one command starts with "te". But if you type '?' to see what they are,
  2704. Kermit shows only "telnet". So why the beep? Because of invisible
  2705. keywords like "telopt", "terminal", and "text". Lots of keywords are
  2706. invisible because they are either synonyms for other keywords or else
  2707. esoteric options to be used only in special circumstances, so we don't
  2708. want them cluttering up the menus.
  2709. But then there is no way for you to discover them. So in C-Kermit 7.0,
  2710. if you type '?' AFTER the beginning of a keyword field, then invisible
  2711. keywords are shown too:
  2712. C-Kermit> te<Esc><BEEP>
  2713. C-Kermit> te? Command, one of the following:
  2714. telnet telopt terminal text
  2715. C-Kermit>te
  2716. But if '?' is typed at the beginning of a field, only visible keywords
  2717. are shown, as before (so, in this example, if '?' is typed at the
  2718. C-Kermit> prompt, "telnet" is the only command shown that starts with
  2719. "te").
  2720. 2. MAKING AND USING CONNECTIONS The SET LINE, SET HOST, and SET PORT (a
  2721. synonym for SET LINE) commands have new synonyms, in which the word SET is
  2722. replaced by the word OPEN: OPEN LINE, etc. There is no new functionality
  2723. here, but OPEN is a better verb, since SET generally takes no action, whereas
  2724. these commands actually try to open a connection. Furthermore, there is the
  2725. symmetry with CLOSE. 2.0. SET LINE and SET HOST Command SwitchesThe SET LINE
  2726. (SET PORT) and SET HOST commands now allow switches before the device or host
  2727. name, in most cases, and under certain circumstances, also at the end. The
  2728. new syntax is backwards compatible with the previous syntax; thus SET LINE,
  2729. SET PORT, and SET HOST commands in command files written for C-Kermit 6.0 or
  2730. earlier still work. The expanded syntax is:
  2731. { OPEN, SET } { LINE, PORT, HOST } [ switches ] device-or-address [ switches
  2732. ]
  2733. The first group of switches is:
  2734. /NETWORK-TYPE:{TCP/IP,X.25,PIPE,PTY...}
  2735. When more than one network type is available, this lets you
  2736. specify the type of network to use for this connection without
  2737. affecting your global SET NETWORK TYPE. See Section 2.7
  2738. about pipes and ptys.
  2739. /USERID:[string]
  2740. This switch is equivalent to SET LOGIN USERID. If a string is
  2741. given, it sent to host during Telnet negotiations; if this
  2742. switch is given but the string is omitted, no user ID is sent to
  2743. the host. If this switch is not given, your current LOGIN USERID
  2744. (\v(userid) value), if any, is sent. Unlike most other switches,
  2745. this one is "sticky", since the value must persist throughout
  2746. the session in case the server requests the ID string at a later
  2747. time.
  2748. /CONNECT
  2749. Enter CONNECT mode immediately and automatically after the
  2750. device or connection is open. On serial devices, however, when
  2751. CARRIER-WATCH is not OFF, wait up to 1 second for the Carrier
  2752. Detect signal to appear before trying to connect, to give the
  2753. device time to react DTR, which might have been off prior to
  2754. opening the device.
  2755. /SERVER
  2756. Enter server mode immediately and automatically after the device
  2757. or connection is open. Treatment of carrier is the same as for
  2758. /CONNECT.
  2759. /WAIT
  2760. /NOWAIT
  2761. For Telnet connections only: Like SET TELNET WAIT { ON, OFF },
  2762. but applies only to this connection, and in fact applies only
  2763. when OPENing this connection (which is usually the only place it
  2764. matters). Typically you would use TELNET /NOWAIT to make a
  2765. connection to a misbehaving Telnet server that does not reply to
  2766. negotiations as required by the Telnet protocol definition.
  2767. Note: /CONNECT and /SERVER switches are not available in the RLOGIN and
  2768. TELNET commands, since these commands already include an implicit
  2769. /CONNECT and preclude automatic entry into server mode.
  2770. The /CONNECT and /SERVER switches are especially useful with "set host
  2771. *" connections. For example, suppose you want to start a Kermit server
  2772. on socket 3000 of your TCP host. Normally you would have to give the
  2773. command:
  2774. set host * 3000
  2775. and then wait for a connection to come in, and only then could you give
  2776. the SERVER command (or else define a macro to do this, and then execute
  2777. the macro). Now you can do it in one step:
  2778. set host /server * 3000
  2779. This tells C-Kermit to wait for the connection and then enter server
  2780. mode once it comes in, no matter how long it takes. Similarly, "set
  2781. host /conn *" can be used to wait for a "chat" connection to come in.
  2782. Another set of switches is available in VMS only, for use only with SET
  2783. LINE:
  2784. /SHARE
  2785. Allows the SET LINE device to be opened in shared mode. Normally
  2786. it makes no sense to open a serial device in shared mode, but
  2787. it's necessary when C-Kermit is running in an environment such
  2788. as DECIntact, that opens your job's controlling terminal in such
  2789. a way that C-Kermit can't open it too, unless it enables SHARE
  2790. privilege. Note: SHARE privilege is required.
  2791. /NOSHARE
  2792. Requires that the SET LINE device not be in use by any other
  2793. process in order for it to be successfully opened by C-Kermit.
  2794. If neither /SHARE nor /NOSHARE is specified, /NOSHARE is used.
  2795. The second group of switches is:
  2796. /NO-TELNET-INIT
  2797. Do not send initial Telnet negotiations even if this is a Telnet
  2798. port.
  2799. /RAW-SOCKET
  2800. This is a connection to a raw TCP socket ( Section 2.3.5).
  2801. /RLOGIN
  2802. Use Rlogin protocol even if this is not an Rlogin port.
  2803. /TELNET
  2804. Send initial Telnet negotiations even if this is not a Telnet
  2805. port.
  2806. As of C-Kermit 7.0 and K95 1.1.19, the TELNET command includes an
  2807. implicit /TELNET switch. So if you TELNET to a non-TELNET port, Kermit
  2808. sends initial Telnet negotiations. This makes sense, since that's what
  2809. "telnet" means.
  2810. If you want to make a connection to a non-Telnet port without sending
  2811. initial Telnet negotiations, use:
  2812. set host [ /connect ] name-or-address port
  2813. or:
  2814. telnet name-or-address port /no-telnet-init
  2815. Additional switches might be added in the future; type "set host ?" or
  2816. "set line ?" to see a current list.
  2817. 2.1. Dialing
  2818. Automatic redialing is illegal or restricted in many countries, so
  2819. until C-Kermit 7.0, it was disabled by default, i.e. until a SET DIAL
  2820. RETRIES command was given. In C-Kermit 7.0, if no SET DIAL RETRIES
  2821. command has been given, a default is picked dynamically at DIAL time
  2822. based on the calling country code, if known. At this writing, the only
  2823. country code known to have no restrictions on automatic redialing is 1.
  2824. So in this case a limit of 10 is chosen; otherwise 1. If you have not
  2825. given an explicit SET DIAL RETRIES command, SHOW DIAL shows the value
  2826. as "(auto)", and then the value actually used is shown when you give
  2827. the DIAL command.
  2828. As of C-Kermit 7.0, automatic redialing is automatically canceled if
  2829. the call could not be placed because no dialtone was detected.
  2830. 2.1.1. The Dial Result Message
  2831. If DIAL DISPLAY is not ON, the "Call complete" message now shows the
  2832. modem's call result message, for example:
  2833. Dialing: ...
  2834. Call complete: "CONNECT 31200/ARQ/V32/LAPM/V42BIS"
  2835. The exact format and contents of this message, of course, depends on
  2836. the make, model, and configuration of your modem, so use your modem
  2837. manual to interpret it. The call result message is also available in
  2838. C-Kermit's \v(dialresult) variable.
  2839. C-Kermit> echo \v(dialresult)
  2840. CONNECT 31200/ARQ/V32/LAPM/V42BIS
  2841. C-Kermit> echo Speed = \fword(\v(dialresult),2)
  2842. Speed = 31200
  2843. C-Kermit>
  2844. Suppose your modem reports the modulation speed as shown above and you
  2845. want to ensure your call is completed at (say) 24000 bps or more. You
  2846. can use a little macro to do the job:
  2847. define HSDIAL { ; High Speed DIAL
  2848. local \%s
  2849. if < \v(argc) 1 if not def \v(dialnumber) end 1 Usage: \%0 number
  2850. set dial retries 100
  2851. set dial interval 1
  2852. while true {
  2853. dial \%*
  2854. if fail end 1 DIAL failed.
  2855. asg \%s \fword(\v(dialresult),2)
  2856. if def \%s if numeric \%s if not < \%s 24000 break
  2857. }
  2858. }
  2859. (See Section 7.5 about the \%* variable.)
  2860. 2.1.2. Long-Distance Dialing Changes
  2861. Due to the glut of cell phones, pagers, fax machines, ISPs, etc, area
  2862. codes and dialing rules are changing all the time. In the North
  2863. American Numbering Plan (NANP) countries (USA, Canada, etc), area codes
  2864. are split or overlayed with increasing frequency, and 10- and 11-digit
  2865. dialing is gradually becoming the norm for local calls. Changes are
  2866. occurring In Europe, too, partly for these reasons and partly because
  2867. of some new EC rules.
  2868. In France, effective 18 October 1996, all calls, even local ones, must
  2869. be dialed with an area code. French area codes are presently 1-digit
  2870. numbers, 1-6, and the long-distance dialing prefix is 0. All calls
  2871. within France are considered long distance and begin with 01, 02, ...,
  2872. 06.
  2873. Effective 1 May 1997, all calls within the US state of Maryland, even
  2874. local ones, must be dialed with an area code but without the
  2875. long-distance prefix -- this is the now widely-known North American
  2876. phenomenon of "ten digit dialing". The same is happening elsewhere --
  2877. many cities in Florida adopted 10-digit dialing in 1998.
  2878. In Italy beginning 19 June 1998, all calls to fixed (as opposed to
  2879. mobile) numbers must be prefixed by 0. When calling into Italy from
  2880. outside, the 0 must follow the country code (39). Calls to cell phones,
  2881. however, must be placed without the 0. Then on 29 December 2000, the 0
  2882. will become a 4 (for calling fixed numbers) and a prefix of 3 must used
  2883. for calling mobile phones. More info at:
  2884. http://www.telecomitalia.it/npnn/.
  2885. In Spain, effective 4 April 1998, with hard cutover on 18 July 1998,
  2886. all calls within the country must be dialed with 9 digits, and all
  2887. calls from outside Spain must also be dialed with 9 digits (after the
  2888. country code, 34). The new 9-digit numbers all begin with "9". More
  2889. info at:http://www.telefonica.es/cambiodenumeracion/
  2890. Several new dialing features and commands have been added in version
  2891. 6.1 and 7.0 to address these changes.
  2892. C-Kermit 6.0 and Kermit 95 1.1.11 and earlier handle the French
  2893. situation via a reasonable subterfuge (setting the local area code to a
  2894. nonexistent one), but did not handle "ten-digit dialing" well at all;
  2895. the recommended technique was to change the long-distance dialing
  2896. prefix to nothing, but this defeated Kermit's "list numbers for one
  2897. name" feature when the numbers were in different locations. For
  2898. example:
  2899. set dial ld-prefix
  2900. dial onlineservice
  2901. where "onlineservice" is a dialing directory entry name corresponding
  2902. to entries that are in (say) Maryland as well as other states, would
  2903. not correctly dial the numbers not in Maryland.
  2904. A new command lets you specify a list of area codes to be considered
  2905. local, except that the area code must be dialed:
  2906. SET DIAL LC-AREA-CODES [ areacode [ areacode [ areacode [ ... ] ] ] ]
  2907. The list may include up to 32 area codes. If a number is called
  2908. whose area code is in this list, it is dialed WITHOUT the
  2909. long-distance prefix, but WITH the area code.
  2910. So in Maryland, which (last time we looked) has two area codes, 410 and
  2911. 301, the setup would be:
  2912. SET DIAL LC-AREA-CODES 410 301
  2913. Example:
  2914. SET DIAL LD-PREFIX 1
  2915. SET DIAL AREA-CODE 301
  2916. SET DIAL LC-AREA-CODES 410 301 <-- Area codes in 10-digit dialing region
  2917. DIAL +1 (301) 765-4321 <-- Dials 3017654321 (local with area code)
  2918. DIAL +1 (410) 765-4321 <-- Dials 4107654321 (local with area code)
  2919. DIAL +1 (212) 765-4321 <-- Dials 12127654321 (long distance)
  2920. The SET DIAL LC-AREA-CODES command does not replace the SET DIAL
  2921. AREA-CODE command. The latter specifies the area code you are dialing
  2922. from. If the called number is in the same area code, then the area code
  2923. is dialed if it is also in the LC-AREA-CODES list, and it is not dialed
  2924. otherwise. So if "301" had not appeared in the LC-AREA-CODES list in
  2925. the previous example:
  2926. SET DIAL LD-PREFIX 1
  2927. SET DIAL AREA-CODE 301
  2928. SET DIAL LC-AREA-CODES 410 <-- Area codes in 10-digit dialing region
  2929. DIAL +1 (301) 765-4321 <-- Dials 7654321 (local)
  2930. DIAL +1 (410) 765-4321 <-- Dials 4107654321 (local with area code)
  2931. DIAL +1 (212) 765-4321 <-- Dials 12127654321 (long distance)
  2932. The new Kermit versions also add a Local Call Prefix and Local Call
  2933. Suffix, in case you have any need for it. These are added to the
  2934. beginning and of local phone numbers (i.e. numbers that are not
  2935. long-distance or international). Examples:
  2936. SET DIAL LD-PREFIX 1
  2937. SET DIAL LC-PREFIX 9
  2938. SET DIAL LC-SUFFIX *
  2939. SET DIAL LC-AREA-CODES 410 <-- Area codes in 10-digit dialing region
  2940. SET DIAL AREA-CODE 301
  2941. DIAL +1 (301) 765-4321 <-- Dials 97654321* (local)
  2942. DIAL +1 (410) 765-4321 <-- Dials 94107654321* (local with area code)
  2943. DIAL +1 (212) 765-4321 <-- Dials 12127654321 (long distance)
  2944. 2.1.3. Forcing Long-Distance Dialing
  2945. Suppose a number is in your country and area, but for some reason you
  2946. need to dial it long-distance anyway (as is always the case in France).
  2947. There have always been various ways to handle this:
  2948. 1. Temporarily set your area code to a different (or nonexistent or
  2949. impossible) one (but this required knowledge of which area codes
  2950. were nonexistent or impossible in each country).
  2951. 2. Dial the number literally instead of using the portable format, but
  2952. this defeats the purpose of the portable dialing directory.
  2953. Now there is also a new command that, very simply, can force
  2954. long-distance dialing:
  2955. SET DIAL FORCE-LONG-DISTANCE { ON, OFF }
  2956. If a call is placed to a portable phone number within the same
  2957. country code as the calling number, it is dialed with the
  2958. long-distance prefix and the area code if FORCE-LONG-DISTANCE is
  2959. ON. If OFF, the regular rules and procedures apply.
  2960. Example (France):
  2961. SET DIAL COUNTRY-CODE 33
  2962. SET DIAL AREA-CODE 6
  2963. SET DIAL FORCE-LONG-DISTANCE ON
  2964. (In fact, SET DIAL COUNTRY-CODE 33 automatically sets DIAL
  2965. FORCE-LONG-DISTANCE ON...)
  2966. Example (USA, for a certain type of reverse-charge calling in which the
  2967. called number must always be fully specified):
  2968. SET DIAL PREFIX 18002666328$ ; 1-800-COLLECT
  2969. SET DIAL COUNTRY-CODE 1
  2970. SET DIAL AREA-CODE 212
  2971. SET DIAL FORCE-LONG-DISTANCE ON
  2972. Example (Toronto, where calls to exchange 976 within area code 416 must
  2973. be dialed as long distance, even when you are dialing from area code
  2974. 416):
  2975. SET DIAL COUNTRY-CODE 1
  2976. SET DIAL AREA-CODE 416
  2977. SET DIAL FORCE-LONG-DISTANCE ON
  2978. DIAL +1 (416) 976-xxxx
  2979. If dialing methods were consistent and sensible, of course it would be
  2980. possible to always dial every domestic call as if it were long
  2981. distance. But in many locations this doesn't work or if it does, it
  2982. costs extra. The following macro can be used for dialing any given
  2983. number with forced long-distance format:
  2984. define LDIAL {
  2985. local \%x
  2986. set dial force-long-distance on
  2987. dial \%*
  2988. asg \%x \v(success)
  2989. set dial force-long-distance off
  2990. end \%x
  2991. }
  2992. (See Section 7.5 about the \%* variable.)
  2993. 2.1.4. Exchange-Specific Dialing Decisions
  2994. This applies mainly to the North American Numbering Plan (NANP). Refer
  2995. to the section "Alternative notations" inUsing C-Kermit 2nd
  2996. Edition, pages 106-107, and the story about Toronto on page 110. Using
  2997. the new LC-AREA-CODES list, we can address the problem by treating the
  2998. exchange as part of the area code:
  2999. SET DIAL LD-PREFIX 1
  3000. SET DIAL AREA-CODE 416
  3001. SET DIAL LC-AREA-CODES 905276
  3002. DIAL +1 416 765 4321 <-- 7654321 (local)
  3003. DIAL +1 905 276 4321 <-- 9052764321 (local with area code)
  3004. DIAL +1 905 528 4321 <-- 19055284321 (long distance)
  3005. The same technique can be used in Massachusetts (story at top of page
  3006. 111) and in any other place where dialing to some exchanges within a
  3007. particular area code is local, but to others in the same area code is
  3008. long distance.
  3009. 2.1.5. Cautions about Cheapest-First Dialing
  3010. Kermit does not maintain a knowledge base of telephony information; it
  3011. only provides the tools to let you enter a phone number in a standard
  3012. format and dial it correctly from any location in most cases.
  3013. In particular, Kermit does not differentiate the charging method from
  3014. the dialing method. If a call that is DIALED as long-distance (e.g.
  3015. from 212 to 718 in country code 1) is not CHARGED as long distance, we
  3016. have no way of knowing that without keeping a matrix of charging
  3017. information for every area-code combination within every country, and
  3018. any such matrix would be obsolete five minutes after it was
  3019. constructed. Thus, "cheapest-first" sorting is only as reliable as our
  3020. assumption that the charging method follows the dialing method. A good
  3021. illustration would be certain online services that have toll-free
  3022. dialup numbers which they charge you a premium (in your online service
  3023. bill) for using.
  3024. 2.1.6. Blind Dialing (Dialing with No Dialtone)
  3025. C-Kermit's init string for Hayes-like modems generally includes an X4
  3026. command to enable as many result codes as possible, so that Kermit can
  3027. react appropriately to different failure reasons. One of the result
  3028. codes that X4 enables is "NO DIALTONE". A perhaps not obvious side
  3029. effect of enabling this result code that the modem must hear dialtone
  3030. before it will dial.
  3031. It is becoming increasingly necessary to force a modem to dial even
  3032. though it does not hear a dialtone on the phone line; for example, with
  3033. PBXs that have strange dialtones, or with phone systems in different
  3034. countries, or with ISDN phones, etc. This is called "blind dialing".
  3035. C-Kermit 7.0 has two new commands to cope with this situation:
  3036. SET DIAL IGNORE-DIALTONE { ON, OFF }
  3037. OFF (the default) means to tell the modem to wait for dialtone
  3038. before dialing. ON means to enable "blind dialing", i.e. tell
  3039. the modem NOT to wait for dialtone before dialing. Generally
  3040. this is accomplished by sending ATX3 to the modem just prior to
  3041. dialing. SET MODEM TYPE xxx and then SHOW MODEM displays
  3042. Kermit's built-in "ignore dialtone" command.
  3043. SET DIAL COMMAND IGNORE-DIALTONE text
  3044. This lets you change the built-in ignore-dialtone command (such
  3045. as ATX3) to whatever you choose, in case the built-in one does
  3046. not work, or another command works better.
  3047. Notes:
  3048. 1. The ignore-dialtone command is not sent unless SET DIAL
  3049. IGNORE-DIALTONE is ON.
  3050. 2. The ATX3 command generally disables not only NO DIALTONE, but also
  3051. BUSY. So this will prevent Kermit from detecting when the line is
  3052. busy. This is a property of the modem, not of Kermit.
  3053. 2.1.7. Trimming the Dialing Dialog
  3054. The command:
  3055. SET MODEM COMMAND action [ command ]
  3056. is used to override Kermit's built-in modem commands for each action,
  3057. for each kind of modem in its internal database. If you include a
  3058. command, this is used instead of the built-in one. If you omit the
  3059. command, this restores the original built-in command.
  3060. If you want to omit the command altogether, so Kermit doesn't send the
  3061. command at all, or wait for a response, use:
  3062. SET MODEM COMMAND action {}
  3063. That is, specify a pair of empty braces as the command, for example:
  3064. SET MODEM COMMAND ERROR-CORRECTION ON {}
  3065. 2.1.8. Controlling the Dialing Speed
  3066. The rate at which characters are sent to the modem during dialing is
  3067. normally controlled by the built-in modem database. You might want to
  3068. override this if Kermit seems to be dialing too slowly, or it is
  3069. sending characters to the modem faster than the modem handle them. A
  3070. new command was added for this in C-Kermit 7.0:
  3071. SET DIAL PACING number
  3072. Specifies the number of milliseconds (thousandths of seconds) to
  3073. pause between each character when sending commands to the modem
  3074. during DIAL or ANSWER command execution. 0 means no pause at
  3075. all, -1 (the default) or any other negative number means to use
  3076. the value from the database. Any number greater than 0 is the
  3077. number of milliseconds to pause.
  3078. HINT: You might also need to control the rate at which the modem
  3079. generates Touch Tones during dialing, for example when sending a
  3080. numeric page. There are two ways to do this. One way is to insert pause
  3081. characters into the dialing string. For modems that use the AT command
  3082. set, the pause character is comma (,) and causes a 2-second pause. On
  3083. most modems, you can use the S8 register to change the pause interval
  3084. caused by comma in the dialing string. The other way is to set your
  3085. modem's tone generation interval, if it has a command for that. Most
  3086. AT-command-set modems use S11 for this; the value is in milliseconds.
  3087. For example on USR modems:
  3088. ATS11=200
  3089. selects an interval of 200 milliseconds to separate each dialing tone.
  3090. Hint: To add S-Register settings or other commands to your dialing
  3091. procedure, use the new SET MODEM COMMAND PREDIAL-INIT command
  3092. ( Section 2.2.2).
  3093. 2.1.9. Pretesting Phone Number Conversions
  3094. The LOOKUP command now accepts telephone numbers as well as
  3095. directory-entry names, for example:
  3096. LOOKUP +1 (212) 7654321
  3097. When given a phone number, LOOKUP prints the result of converting the
  3098. phone number for dialing under the current dialing rules. For example,
  3099. if my country code is 1 and my area code is 212, and I am dialing out
  3100. from a PBX whose outside-line prefix is "93,":
  3101. C-Kermit> lookup +1 (212) 7654321
  3102. +1 (212) 7654321 => 93,7654321
  3103. C-Kermit>
  3104. You can also use the \fdialconvert(phone-number) function (Section
  3105. 2.1.11) to do this programmatically:
  3106. C-Kermit> echo "\fdialconvert(+1 (212) 7654321)"
  3107. "93,7654321"
  3108. C-Kermit>
  3109. So the new LOOKUP behaves as follows:
  3110. LOOKUP portable-format-phone-number
  3111. Displays how the number would actually be dialed Sets FAILURE if
  3112. there was a conversion error, otherwise SUCCESS.
  3113. LOOKUP literal-format-phone-number
  3114. Displays the same literal-format-phone-number Always sets
  3115. SUCCESS.
  3116. LOOKUP dialing-directory-name
  3117. Displays all matching entries and converts portable phone
  3118. numbers. Sets SUCCESS if at least one entry was found, otherwise
  3119. FAILURE.
  3120. LOOKUP =anything
  3121. Displays "=anything" and sets SUCCESS.
  3122. There is, at present, no programmatic way to fetch numbers from the
  3123. dialing directory. This will be considered for a future release.
  3124. 2.1.10. Greater Control over Partial Dialing
  3125. The following rules now apply to partial dialing:
  3126. * Phone number transformations based on country and area code,
  3127. application of prefixes, etc, are performed only on the first
  3128. PDIAL.
  3129. * Each PDIAL argument is looked up in the dialing directory, so it is
  3130. possible have directory entries for pieces of phone numbers or
  3131. other information.
  3132. * Suffixes are not applied automatically, since there is no way for
  3133. C-Kermit to know in which PDIAL segment you want them to be
  3134. applied.
  3135. However, the suffix that *would* have been applied, based on the
  3136. dialing rules that were invoked when processing the first PDIAL
  3137. command, is stored in the variable:
  3138. \v(dialsuffix)
  3139. which you can include in any subsequent PDIAL or DIAL commands.
  3140. Example:
  3141. pdial {\m(my_long_distance_pager_number_part_1)}
  3142. pdial {\m(my_long_distance_pager_number_part_2)}
  3143. pdial {\v(dialsuffix)}
  3144. pdial {\m(my_long_distance_pager_number_part_3)}
  3145. pdial {@\m(numeric_pager_code)#}
  3146. 2.1.11. New DIAL-related Variables and Functions
  3147. \fdialconvert(s)
  3148. s is a phone number in either literal or portable format (not a
  3149. dialing directory entry name). The function returns the dial
  3150. string that would actually be used by the DIAL command when
  3151. dialing from the current location, after processing country
  3152. code, area code, and other SET DIAL values, and should be the
  3153. same as the result of LOOKUP when given a telephone number.
  3154. \v(dialsuffix)
  3155. Contains the suffix, if any, that was applied in the most recent
  3156. DIAL command, or the suffix that would have been applied in the
  3157. most recent PDIAL command. Use this variable to send the dial
  3158. suffix at any desired point in a PDIAL sequence.
  3159. \v(dialtype)
  3160. A number indicating the type of call that was most recently
  3161. placed. Can be used after a normal DIAL command, or after the
  3162. first PDIAL command in a PDIAL sequence. Values are:
  3163. -2: Unknown because TAPI handled the phone number translation.
  3164. -1: Unknown because some kind of error occurred.
  3165. 0: Internal within PBX.
  3166. 1: Toll-free.
  3167. 2: Local within calling area.
  3168. 3: Unknown (e.g. because a literal-format phone number was given).
  3169. 4: Long distance within country.
  3170. 5: International
  3171. \v(dialcount)
  3172. The current value of the DIAL retry counter, for use in a DIAL
  3173. macro ( Section 2.1.13).
  3174. \v(d$px)
  3175. PBX Exchange (see Section 2.1.12).
  3176. Other dial-related variables, already documented inUsing C-Kermit
  3177. (or other sections of this document, e.g. Section 2.1.1), include
  3178. \v(dialnumber), \v(dialstatus), etc. A convenient way to display all of
  3179. them is:
  3180. show variable dial ; hint: abbreviate "sho var dial"
  3181. This shows the values of all the variables whose names start with
  3182. "dial". Also "show variable d$" (to show the \v(d$...) variables).
  3183. 2.1.12. Increased Flexibility of PBX Dialing
  3184. Refer toUsing C-Kermit, 2nd Edition, pages 107-108. Recall that
  3185. three commands are needed to configure C-Kermit for dialing from a PBX:
  3186. SET DIAL PBX-EXCHANGE number
  3187. SET DIAL PBX-INSIDE-PREFIX number
  3188. SET DIAL PBX-OUTSIDE-PREFIX number
  3189. Unfortunately, this model does not accommodate PBXs that have more than
  3190. one exchange. For example our PBX at Columbia University (which must
  3191. handle more than 10,000 phones) has 853-xxxx and 854-xxxx exchanges.
  3192. Beginning in C-Kermit 7.0, the SET DIAL PBX-EXCHANGE command accepts a
  3193. list of exchanges, e.g.:
  3194. SET DIAL PBX-EXCHANGE 853 854
  3195. (multiple exchanges are separated by spaces, not commas).
  3196. So now when dialing a portable-format number that has the same country
  3197. and area codes as those of your dialing location, C-Kermit compares the
  3198. exchange of the dialed number with each number in the PBX Exchange list
  3199. (rather than with a single PBX Exchange number, as it did formerly) to
  3200. determine whether this is an internal PBX number or an external call.
  3201. If it is an external call, then the PBX Outside Prefix is applied, and
  3202. then the normal dialing rules for local or long-distance calls.
  3203. If it is an inside call, the exchange is replaced by the PBX Inside
  3204. Prefix. But if the PBX has more than one exchange, a single fixed PBX
  3205. Inside Prefix is probably not sufficient. For example, at Columbia
  3206. University, we must dial 3-xxxx for an internal call to 853-xxxx, but
  3207. 4-xxxx for a call to 854-xxxx. That is, the inside prefix is the final
  3208. digit of the exchange we are dialing. For this reason, C-Kermit 7.0
  3209. provides a method to determine the inside prefix dynamically at dialing
  3210. time, consisting of a new variable and new syntax for the SET DIAL
  3211. PBX-INSIDE-PREFIX command:
  3212. \v(d$px)
  3213. This variable contains the exchange that was matched when a PBX
  3214. internal call was detected. For example, if the PBX exchange
  3215. list is "853 854" and a call is placed to +1 (212) 854-9999,
  3216. \v(d$px) is set to 854.
  3217. SET DIAL PBX-INSIDE-PREFIX \fxxx(...)
  3218. If the PBX Inside Prefix is defined to be a function, its
  3219. evaluation is deferred until dialing time. Normally, this would
  3220. be a string function having \v(d$px) as an operand. Of course,
  3221. you can still specify a constant string, as before.
  3222. So given the following setup:
  3223. SET DIAL COUNTRY-CODE 1
  3224. SET DIAL AREA-CODE 212
  3225. SET DIAL PBX-OUTSIDE-PREFIX 93,
  3226. SET DIAL PBX-EXCHANGE 853 854
  3227. SET DIAL PBX-INSIDE-PREFIX \fright(\v(d$px),1)
  3228. The following numbers give the results indicated:
  3229. Number Result
  3230. +1 (212) 854-9876 4-9876
  3231. +1 (212) 853-1234 3-1234
  3232. +1 (212) 765-4321 93,765-4321
  3233. +1 (333) 765-4321 93,1333765-4321
  3234. Furthermore, the K_PBX_XCH environment variable may now be set to a
  3235. list of exchanges to automatically initialize C-Kermit's PBX exchange
  3236. list, for example (in UNIX ksh or bash):
  3237. export K_PBX_XCH="853 854"
  3238. (Quotes required because of the space.) Of course, this variable can
  3239. also be set to a single exchange, as before:
  3240. export K_PBX_XCH=853
  3241. 2.1.13. The DIAL macro - Last-Minute Phone Number Conversions
  3242. After a DIAL or LOOKUP command is given, a list of phone numbers is
  3243. assembled from the dialing directory (if any), with all
  3244. location-dependent conversion rules applied as described in Chapter 5
  3245. ofUsing C-Kermit.
  3246. However, additional conversions might still be required at the last
  3247. minute based on local or ephemeral conditions. So that you can have the
  3248. final word on the exact format of the dial string, C-Kermit 7.0 lets
  3249. you pass the converted string through a macro of your own design for
  3250. final processing before dialing. The relevant command is:
  3251. SET DIAL MACRO [ name ]
  3252. Specifies the name of a macro to be run on each phone number
  3253. after all built-in conversions have been applied, just before
  3254. the number is dialed. If no name is given, no macro is run. The
  3255. phone number, as it would have been dialed if there were no dial
  3256. macro, is passed to the macro.
  3257. The dial macro can do anything at all (except start a file transfer).
  3258. However, the normal use for the macro would be to modify the phone
  3259. number. For this reason the phone number is passed to the macro as
  3260. argument number 1 (\%1). To cause a modified number to be dialed, the
  3261. macro should terminate with a RETURN statement specifying a return
  3262. value. To leave the number alone, the macro should simply end. Example:
  3263. define xxx return 10108889999$\%1
  3264. set dial macro xxx
  3265. dial xyzcorp
  3266. This defines a DIAL MACRO called xxx, which puts an access code on the
  3267. front of the number. Another example might be:
  3268. def xxx if equal "\v(modem)" "hayes-1200" return \freplace(\%1,$,{,,,,,})
  3269. set dial macro xxx
  3270. dial xyzcorp
  3271. which replaces any dollar-sign in the dial string by a series of five
  3272. commas, e.g. because this particular modem does not support the "wait
  3273. for bong" feature (remember that commas that are to be included
  3274. literally in function arguments must be enclosed in braces to
  3275. distinguish them from the commas that separate the arguments) and when
  3276. the IF condition is not satisfied, the macro does not return a value,
  3277. and so the number is not modified. Then when a DIAL command is given
  3278. referencing a dialing directory entry, "xyzcorp". The macro is
  3279. automatically applied to each matching number.
  3280. Numerous dial-, modem-, communications-, and time-related variables are
  3281. available for decision making your dial macro. Type SHOW VARIABLES for
  3282. a list. Of particular interest is the \v(dialcount) variable, which
  3283. tells how many times the DIAL command gone through its retry loop: 1 on
  3284. the first try, 2 on the second, 3 on the third, and so on, and the
  3285. \v(dialresult) and \v(dialstatus) variables.
  3286. Here are some other applications for the DIAL MACRO (from users):
  3287. * Phone numbers in the dialing directory are formatted with '-' for
  3288. readability, but some modems don't like the hyphens, so the DIAL
  3289. macro is used to remove them before dialing; e.g 0090-123-456-78-99
  3290. becomes 00901234567899: "def xxx return \freplace(\%1,-)".
  3291. * To set some specific modem (or other) options depending on the
  3292. called customer or telephone number.
  3293. * Choosing the most appropriate provider based on (e.g.) time of day,
  3294. or cycling through a list of providers in case some providers might
  3295. be busy.
  3296. To illustrate the final item, suppose you have a choice among many
  3297. phone service providers; the provider is chosen by dialing an access
  3298. code before the number. Different providers might be better (e.g.
  3299. cheaper) for certain times of day or days of the week, or for dialing
  3300. certain locations; you can use the DIAL macro to add the access for the
  3301. most desirable provider.
  3302. Similarly, when the same number might be reached through multiple
  3303. providers, it's possible that one provider might not be able to
  3304. complete the call, but another one can. In that case, you can use the
  3305. DIAL macro to switch providers each time through the DIAL loop --
  3306. that's where the \v(dialcount) variable comes in handy.
  3307. The following command can be used to debug the DIAL macro:
  3308. SET DIAL TEST { ON, OFF }
  3309. Normally OFF, so the DIAL command actually dials. When ON, the
  3310. DIAL command performs all lookups and number conversions, and
  3311. then goes through the number list and retry loop, but instead of
  3312. actually dialing, lists the numbers it would have called if none
  3313. of the DIAL attempts succeeded (or more precisely, every number
  3314. was always busy).
  3315. 2.1.14. Automatic Tone/Pulse Dialing Selection
  3316. SET DIAL METHOD { AUTO, DEFAULT, PULSE, TONE }
  3317. Chooses the dialing method for subsequent calls.
  3318. Prior to version 7.0, C-Kermit's DIAL METHOD was DEFAULT by default,
  3319. meaning it does not specify a dialing method to the modem, but relies
  3320. on the modem to have an appropriate default dialing method set. So, for
  3321. example, when using Hayes compatible modems, the dial string would be
  3322. something like ATD7654321, rather than ATDT7654321 or ATDP7654321.
  3323. In C-Kermit 7.0 and K95 1.1.19, the dial method can be set from the
  3324. environment variable:
  3325. K_DIAL_METHOD
  3326. when Kermit starts. The values can be TONE, PULSE, or DEFAULT, e.g.
  3327. (UNIX):
  3328. set K_DIAL_METHOD=TONE; export K_DIAL_METHOD
  3329. In the absence of a K_DIAL_METHOD definition, the new default SET DIAL
  3330. METHOD is AUTO rather than DEFAULT. When DIAL METHOD is AUTO and the
  3331. local country code is known, then if tone dialing is universally
  3332. available in the corresponding area, tone dialing is used; if dialing
  3333. from a location where pulse dialing is mandatory, pulse dialing is
  3334. used.
  3335. The "tone country" and "pulse country" lists are preloaded according to
  3336. our knowledge at the time of release. You can see their contents in the
  3337. SHOW DIAL listing. You can change the lists with:
  3338. SET DIAL TONE-COUNTRIES [ cc [ cc [ ... ] ] ]
  3339. Replaces the current TONE-COUNTRIES list with the one given.
  3340. Each cc is a country code; separate them with spaces (not
  3341. commas). Example:
  3342. set dial tone-countries 1 358 44 46 49
  3343. If no country codes are given, the current list, if any, is
  3344. removed, in which case SET DIAL METHOD AUTO is equivalent to SET
  3345. DIAL METHOD DEFAULT.
  3346. SET DIAL PULSE-COUNTRIES [ cc [ cc [ ... ] ] ]
  3347. Replaces the current PULSE-COUNTRIES list with the one give.
  3348. Syntax and operation is like SET DIAL TONE-COUNTRIES.
  3349. If the same country code appears in both lists, Pulse takes precedence.
  3350. The SET DIAL TONE- and PULSE-COUNTRIES commands perform no verification
  3351. whatsoever on the cc's, since almost any syntax might be legal in some
  3352. settings. Furthermore, there is no facility to edit the lists; you can
  3353. only replace the whole list. However, since the only purpose of these
  3354. lists is to establish a basis for picking tone or pulse dialing
  3355. automatically, all you need to override the effect of the list is to
  3356. set a specific dialing method with SET DIAL METHOD TONE or SET DIAL
  3357. METHOD PULSE.
  3358. 2.1.15. Dial-Modifier Variables
  3359. As of C-Kermit 7.0, dial modifiers are available in the following
  3360. variables:
  3361. \v(dm_lp) Long pause
  3362. \v(dm_sp) Short pause
  3363. \v(dm_pd) Pulse dial
  3364. \v(dm_td) Tone dial
  3365. \v(dm_wa) Wait for answer
  3366. \v(dm_wd) Wait for dialtone
  3367. \v(dm_rc) Return to command mode
  3368. You can use these in your dial strings in place of hardwired modifiers
  3369. like "@", ",", etc, for increased portability of scripts. Example:
  3370. C-Kermit>set modem type usrobotics
  3371. C-Kermit>sho variables dm
  3372. \v(dm_lp) = ,
  3373. \v(dm_sp) = /
  3374. \v(dm_pd) = P
  3375. \v(dm_td) = T
  3376. \v(dm_wa) = @
  3377. \v(dm_wd) = W
  3378. \v(dm_rc) = ;
  3379. C-Kermit>exit
  3380. 2.1.16. Giving Multiple Numbers to the DIAL Command
  3381. Prior to C-Kermit 7.0, the only way to give a DIAL command a list of
  3382. phone numbers to try until one answers was to create a dialing
  3383. directory that had multiple entries under the same name, and then use
  3384. that entry name in the DIAL command. Now a list of numbers can be given
  3385. to the DIAL command directly in the following format:
  3386. dial {{number1}{number2}{number3}...}
  3387. This is the same list format used by SEND /EXCEPT: and other commands
  3388. that allow a list where normally a single item is given. Restrictions
  3389. on this form of the DIAL command are:
  3390. * The first two braces must be adjacent; spacing is optional
  3391. thereafter.
  3392. * Each number must be an actual number to dial, not a dialing
  3393. directory entry.
  3394. * Dialing directory entries may not contain number lists in this
  3395. format.
  3396. In all other respects, the numbers are treated as if they had been
  3397. fetched from the dialing directory; they can be in literal or portable
  3398. format, etc. Example:
  3399. dial {{7654321} {+1 (212) 5551212} { 1-212-5556789 }}
  3400. The list can be any length at all, within reason.
  3401. This feature is especially handy for use with the K95 Dialer, allowing
  3402. a list of phone numbers to be specified in the Telephone Number box
  3403. without having to set up or reference a separate dialing directory.
  3404. You can also use it to add commonly-dialed sequences as variables in
  3405. your C-Kermit customization file, e.g.:
  3406. define work {{7654321}{7654322}{7654323}}
  3407. and then:
  3408. dial {\m(work)}
  3409. (the variable name must be enclosed in braces).
  3410. Or more simply:
  3411. define work dial {{7654321}{7654322}{7654323}}
  3412. and then:
  3413. work
  3414. 2.2. Modems
  3415. 2.2.1. New Modem Types
  3416. Since C-Kermit 6.0:
  3417. atlas-newcom-33600ifxC Atlas/Newcom 33600
  3418. att-keepintouch AT&T KeepinTouch PCMCIA V.32bis Card Modem
  3419. att-1900-stu-iii AT&T Secure Data STU-III Model 1900
  3420. att-1910-stu-iii AT&T Secure Data STU-III Model 1910
  3421. bestdata Best Data
  3422. cardinal Cardinal V.34 MVP288X series.
  3423. compaq Compaq Data+Fax (e.g. in Presario)
  3424. fujitsu Fujitsu Fax/Modem Adapter
  3425. generic-high-speed Any modern error-correcting data-compressing modem
  3426. itu-t-v25ter/v250 ITU-T (CCITT) V.25ter (V.250) standard command set
  3427. megahertz-att-v34 Megahertz AT&T V.34
  3428. megahertz-xjack Megahertz X-Jack
  3429. motorola-codex Motorola Codex 326X Series
  3430. motorola-montana Motorola Montana
  3431. mt5634zpx Multitech MT5634ZPX
  3432. rockwell-v90 Rockwell V.90 56K
  3433. rolm-244pc Siemens/Rolm 244PC (AT command set)
  3434. rolm-600-series Siemens/Rolm 600 Series (AT command set)
  3435. spirit-ii QuickComm Spirit II
  3436. suprasonic SupraSonic V288+
  3437. supra-express-v90 Supra Express V.90
  3438. One of the new types, "generic-high-speed" needs a bit of explanation.
  3439. This type was added to easily handle other types that are not
  3440. explicitly covered, without going through the bother of adding a
  3441. complete user-defined modem type. This one works for modern modems that
  3442. use the AT command set, on the assumption that all the default
  3443. ("factory") settings of the modem (a) are appropriate for Kermit, (b)
  3444. include error correction, data compression, and speed buffering; and
  3445. (c) are recallable with the command AT&F.
  3446. If the command to recall your modem's profile is not AT&F, use the SET
  3447. MODEM COMMAND INIT-STRING command to specify the appropriate modem
  3448. command. The default init-string is AT&F\13 (that is, AT, ampersand, F,
  3449. and then carriage return); a survey of about 20 modern modem types
  3450. shows they all support this, but they might mean different things by
  3451. it. For example, the USR Sportster or Courier needs AT&F1 (not AT&F,
  3452. which is equivalent to AT&F0, which recalls an inappropriate profile),
  3453. so for USR modems:
  3454. set modem type generic-high-speed
  3455. set modem command init AT&F1\13
  3456. Of course, USR modems already have their own built-in modem type. But
  3457. if you use this one instead, it will dial faster because it has fewer
  3458. commands to give to the modem; in that sense "&F1" is like a macro that
  3459. bundles numerous commands into a single one. See your modem manual for
  3460. details about factory profiles and commands to recall them.
  3461. WARNING: Do not use the generic-high-speed modem type in operating
  3462. systems like VMS where hardware flow control is not available, at least
  3463. not unless you change the init string from AT&F\13 to something else
  3464. that enables local Xon/Xoff or other appropriate type of flow control.
  3465. Also see Section 2.1.7 for additional hints about making dialing
  3466. go faster.
  3467. 2.2.2. New Modem Controls
  3468. SET MODEM CAPABILITIES list
  3469. In C-Kermit 7.0, this command automatically turns MODEM
  3470. SPEED-MATCHING OFF if SB (Speed Buffering) is in the list, and
  3471. turns it ON if SB is absent.
  3472. SET MODEM COMMAND PREDIAL-INIT [ text ]
  3473. Commands to be sent to the modem just prior to dialing. Normally
  3474. none.
  3475. SET MODEM SPEAKER { ON, OFF }
  3476. Determines whether modem speaker is on or off while call is
  3477. being placed. ON by default. Note: This command does not provide
  3478. fine-grained control over when the speaker is on or off.
  3479. Normally, ON means while the call is being placed, until the
  3480. point at which carrier is successfully established. If your
  3481. modem has a different speaker option that you want to choose,
  3482. then use the SET MODEM COMMAND SPEAKER ON text command to
  3483. specify this option.
  3484. SET MODEM COMMAND SPEAKER { ON, OFF } [ text ]
  3485. Specify or override the commands to turn your modem's speaker on
  3486. and off.
  3487. SET MODEM VOLUME { LOW, MEDIUM, HIGH }
  3488. When MODEM SPEAKER is on, select volume. Note: In some modems,
  3489. especially internal ones, these commands have no effect; this is
  3490. a limitation of the particular modem, not of Kermit.
  3491. SET MODEM COMMAND VOLUME { LOW, MEDIUM, HIGH } [ text ]
  3492. Specify or override the commands to set your modem's speaker
  3493. volume.
  3494. SET MODEM COMMAND IGNORE-DIALTONE [ text ]
  3495. The command to enable blind dialing ( Section 2.1.6).
  3496. SET MODEM ESCAPE-CHARACTER code
  3497. Has been augmented to allow codes of 0 or less: < 0 means the
  3498. escape mechanism is disabled. = 0 means to use (restore) the
  3499. default value from the modem database. > 0 and < 128 is a
  3500. literal value to be used instead of the default one. > 127 means
  3501. the escape mechanism is disabled. This affects "modem hangup".
  3502. When the escape mechanism is disabled, but SET MODEM
  3503. HANGUP-METHOD is MODEM-COMMAND, it sends the hangup command
  3504. immediately, without the <pause>+++<pause> business first. This
  3505. is useful (for example) when sending lots of numeric pages, a
  3506. process in which never we go online, and so never need to escape
  3507. back. Eliminating the unnecessary pauses and escape sequence
  3508. allows a lot more pages to be sent per unit time.
  3509. Recall that C-Kermit can dial modems to which it is connected via
  3510. TCP/IP (Telnet or Rlogin) as described on page 126 ofUsing
  3511. C-Kermit, 2nd Ed. In this case the MODEM HANGUP-METHOD should be
  3512. MODEM-COMMAND, since RS-232 signals don't work over TCP/IP connections.
  3513. As noted in the manual, such connections are set up by the following
  3514. sequence:
  3515. set host host [ port ]
  3516. set modem type name
  3517. dial number
  3518. But this can cause complications when you use Kermit to switch between
  3519. serial and TCP/IP connections. In the following sequence:
  3520. set host name
  3521. set modem type name
  3522. set port name
  3523. the first two commands obey the rules for dialing out over Telnet.
  3524. However, the SET PORT command requires that Kermit close its current
  3525. (Telnet) connection before it can open the serial port (since Kermit
  3526. can only have one connection open at a time). But since a modem type
  3527. was set after the "set host" command was given, Kermit assumes it is a
  3528. Telnet dialout connection and so sends the modem's hangup sequence is
  3529. sent to the Telnet host. To avoid this, close the network connection
  3530. explicitly before opening the serial one:
  3531. set host name
  3532. close
  3533. set modem type name
  3534. set port name
  3535. 2.3. TELNET and RLOGIN
  3536. For additional background, please also read theTELNET.TXT file,
  3537. also available on the Web inHTML format.
  3538. Cautions:
  3539. * If making a Telnet connection with C-Kermit takes a very long time,
  3540. like over a minute, whereas the system Telnet program makes the
  3541. same connection immediately, try including the /NOWAIT switch:
  3542. C-Kermit> telnet /nowait hostname
  3543. SeeTELNET.TXT orTELNET.HTM for details. If it also
  3544. takes a very long time to make a Telnet connection with system
  3545. Telnet, then the delay is most likely caused by reverse DNS lookups
  3546. when your host is not properly registered in DNS.
  3547. * When supplying numeric IP addresses to C-Kermit or to any other
  3548. application (regular Telnet, Rlogin, etc), do not include leading
  3549. 0's in any fields unless you intend for those fields to be
  3550. interpreted as octal (or hex) numbers. The description of the
  3551. Internet address interpreter (the sockets library inet_addr()
  3552. routine) includes these words:
  3553. All numbers supplied as "parts" in a "." notation may be decimal,
  3554. octal, or hexadecimal, as specified in the C language (that is, a
  3555. leading 0x or 0X implies hexadecimal; otherwise, a leading 0 implies
  3556. octal; otherwise, the number is interpreted as decimal).
  3557. To illustrate, 128.59.39.2 and 128.059.039.002 are not the same
  3558. host! Even though most of the fields contain non-octal digits.
  3559. Using system Telnet (not Kermit):
  3560. $ telnet 128.059.039.002
  3561. Trying 128.49.33.2 ...
  3562. Of course the same thing happens with Kermit because it uses (as it
  3563. must) the same system service for resolving network addresses that
  3564. Telnet, FTP, and all other TCP/IP applications use.
  3565. * The RLOGIN section on page 123 does not make it clear that you can
  3566. use the SET TELNET TERMINAL-TYPE command to govern the terminal
  3567. type that is reported by C-Kermit to the RLOGIN server.
  3568. * Note that the SET TCP commands described on pages 122-123 might be
  3569. absent; some platforms that support TCP/IP do not support these
  3570. particular controls.
  3571. New commands:
  3572. TELOPT { AO, AYT, BREAK, CANCEL, EC, EL, EOF, EOR, GA, IP, DMARK,
  3573. DO, DONT, NOP, SB, SE, SUSP, WILL, WONT }
  3574. This command was available previously, but supported only DO,
  3575. DONT, WILL, and WONT. Now it lets you send all the Telnet
  3576. protocol commands. Note that certain commands do not require a
  3577. response, and therefore can be used as nondestructive "probes"
  3578. to see if the Telnet session is still open; e.g.:
  3579. set host xyzcorp.com
  3580. ...
  3581. telopt nop
  3582. if fail stop 1 Connection lost
  3583. SET TCP ADDRESS [ ip-address ]
  3584. Specifies the IP address of the computer that C-Kermit is
  3585. running on. Normally this is not necessary. The exception would
  3586. be if your machine has multiple network adapters (physical or
  3587. virtual) with a different address for each adapter AND you want
  3588. C-Kermit to use a specific address when making outgoing
  3589. connections or accepting incoming connections.
  3590. SET TCP DNS-SERVICE-RECORDS { ON, OFF }
  3591. Tells C-Kermit whether to try to use DNS SRV records to
  3592. determine the host and port number upon which to find an
  3593. advertised service. For example, if a host wants regular Telnet
  3594. connections redirected to some port other than 23, this feature
  3595. allows C-Kermit to ask the host which port it should use. Since
  3596. not all domain servers are set up to answer such requests, this
  3597. feature is OFF by default.
  3598. SET TCP REVERSE-DNS-LOOKUP { ON, OFF, AUTO }
  3599. Tells Kermit whether to perform a reverse DNS lookup on TCP/IP
  3600. connections. This allows Kermit to determine the actual hostname
  3601. of the host it is connected to, which is useful for connections
  3602. to host pools, and is required for Kerberos connections to host
  3603. pools and for incoming connections. If the other host does not
  3604. have a DNS entry, the reverse lookup could take a long time
  3605. (minutes) to fail, but the connection will still be made. Turn
  3606. this option OFF for speedier connections if you do not need to
  3607. know exactly which host you are connected to and you are not
  3608. using Kerberos. AUTO, the default, means the lookup is done on
  3609. hostnames, but not on numeric IP addresses.
  3610. SET TELNET WAIT-FOR-NEGOTIATIONS { ON, OFF }
  3611. Each Telnet option must be fully negotiated either On or Off
  3612. before the session can continue. This is especially true with
  3613. options that require sub-negotiations such as Authentication,
  3614. Encryption, and Kermit; for proper support of these options
  3615. Kermit must wait for the negotiations to complete. Of course,
  3616. Kermit has no way of knowing whether a reply is delayed or not
  3617. coming at all, and so will wait a minute or more for required
  3618. replies before continuing the session. If you know that Kermit's
  3619. Telnet partner will not be sending the required replies, you can
  3620. set this option of OFF to avoid the long timeouts. Or you can
  3621. instruct Kermit to REFUSE specific options with the SET TELOPT
  3622. command.
  3623. SET TELOPT [ { /CLIENT, /SERVER } ] option
  3624. { ACCEPTED, REFUSED, REQUESTED, REQUIRED }
  3625. [ { ACCEPTED, REFUSED, REQUESTED, REQUIRED } ]
  3626. SET TELOPT lets you specify policy requirements for Kermit's
  3627. handling of Telnet option negotiations. Setting an option is
  3628. REQUIRED causes Kermit to offer the option to the peer and
  3629. disconnect if the option is refused. REQUESTED causes Kermit to
  3630. offer an option to the peer. ACCEPTED results in no offer but
  3631. Kermit will attempt to negotiate the option if it is requested.
  3632. REFUSED instructs Kermit to refuse the option if it is requested
  3633. by the peer.
  3634. Some options are negotiated in two directions and accept
  3635. separate policies for each direction; the first keyword applies
  3636. to Kermit itself, the second applies to Kermit's Telnet partner;
  3637. if the second keyword is omitted, an appropriate
  3638. (option-specific) default is applied. You can also include a
  3639. /CLIENT or /SERVER switch to indicate whether the given policies
  3640. apply when Kermit is the Telnet client or the Telnet server; if
  3641. no switch is given, the command applies to the client.
  3642. Note that some of Kermit's Telnet partners fail to refuse
  3643. options that they do not recognize and instead do not respond at
  3644. all. In this case it is possible to use SET TELOPT to instruct
  3645. Kermit to REFUSE the option before connecting to the problem
  3646. host, thus skipping the problematic negotiation.
  3647. Use SHOW TELOPT to view current Telnet Option negotiation
  3648. settings. SHOW TELNET displays current Telnet settings.
  3649. 2.3.0. Bug Fixes
  3650. If "set host nonexistent-host" was given (and it properly failed),
  3651. followed by certain commands like SEND, the original line and modem
  3652. type were not restored and C-Kermit thought that it still had a network
  3653. hostname; fixed in 7.0.
  3654. 2.3.1. Telnet Binary Mode Bug Adjustments
  3655. SET TELNET BUG BINARY-ME-MEANS-U-TOO { ON, OFF } was added to edit 192
  3656. after the book was printed. Also SET TELNET BUG BINARY-U-MEANS-ME-TOO.
  3657. The default for both is OFF. ON should be used when communicating with
  3658. a Telnet partner (client or server) that mistakenly believes that
  3659. telling C-Kermit to enter Telnet binary mode also means that it, too,
  3660. is in binary mode, contrary to the Telnet specification, which says
  3661. that binary mode must be negotiated in each direction separately.
  3662. 2.3.2. VMS UCX Telnet Port Bug Adjustment
  3663. A new command, SET TCP UCX-PORT-BUG, was added for VMS versions with
  3664. UCX (DEC TCP/IP), applying only to early versions of UCX, like 2.2 or
  3665. earlier. If you try to use VMS C-Kermit to make a Telnet connection
  3666. using a port name (like "telnet", which is used by default), the
  3667. underlying UCX getservbyname() function might return the service number
  3668. with its bytes swapped and the connection will fail. If "telnet
  3669. hostname 23" works, then your version of UCX has this bug and you can
  3670. put "set tcp ucx-port-bug on" in your CKERMIT.INI file to get around
  3671. it.
  3672. 2.3.3. Telnet New Environment Option
  3673. The TELNET NEW-ENVIRONMENT option (RFC 1572) is supported as 7.0.
  3674. This option allows the C-Kermit Telnet client to send certain
  3675. well-known variables to the Telnet server, including USER, PRINTER,
  3676. DISPLAY, and several others. This feature is enabled by default in
  3677. Windows and OS/2, disabled by default elsewhere. The command to enable
  3678. and disable it is:
  3679. SET TELNET ENVIRONMENT { ON, OFF }
  3680. When ON, and you Telnet to another computer, you might (or might not)
  3681. notice that the "login:" or "Username:" prompt does not appear --
  3682. that's because your username was sent ahead, in which case the remote
  3683. system might prompt you only for your password (similar to Rlogin). Use
  3684. "set telnet environment off" to defeat this feature, particularly in
  3685. scripts where the dialog must be predictable. You can also use this
  3686. command to specify or override specific well-known environment variable
  3687. values:
  3688. SET TELNET ENVIRONMENT { ACCT,DISPLAY,JOB,PRINTER,SYSTEMTYPE,USER } [ text ]
  3689. 2.3.4. Telnet Location Option
  3690. The TELNET LOCATION option (RFC 779) is supported in 7.0. This
  3691. option allows the C-Kermit Telnet client to send a location string to
  3692. the server if the server indicates its willingness to accept one. If an
  3693. environment variable named LOCATION exists at the time C-Kermit starts,
  3694. its value is used as the location string. If you want to change it,
  3695. use:
  3696. SET TELNET LOCATION text
  3697. If you omit the text from this command, the Telnet location feature is
  3698. disabled.
  3699. SET TELNET ENVIRONMENT DISPLAY is used to set the DISPLAY variable that
  3700. is sent to the host, as well as the XDISPLAY location.
  3701. 2.3.5. Connecting to Raw TCP Sockets
  3702. The SET HOST and TELNET commands now accept an optional switch,
  3703. /RAW-SOCKET, at the end, only if you first give a host and a port.
  3704. Example:
  3705. set host xyzcorp.com 23 /raw-socket
  3706. set host 128.49.39.2:2000 /raw-socket
  3707. telnet xyzcorp.com 3000 /raw
  3708. Without this switch, C-Kermit behaves as a Telnet client when (a) the
  3709. port is 23 or 1649, or (b) the port is not 513 and the server sent what
  3710. appeared to be Telnet negotiations -- that is, messages starting with
  3711. 0xFF (IAC). With this switch, Kermit should treat all incoming bytes as
  3712. raw data, and will not engage in any Telnet negotiations or NVT CRLF
  3713. manipulations. This allows transparent operation through (e.g.) raw TCP
  3714. ports on Cisco terminal servers, through the 'modemd' modem server,
  3715. etc.
  3716. 2.3.6. Incoming TCP Connections
  3717. Accomplished via SET HOST * port, were introduced in C-Kermit 6.0, but
  3718. for UNIX only. In Version 7.0, they are also available for VMS.
  3719. 2.4. The EIGHTBIT Command
  3720. EIGHTBIT is simply a shorthand for: SET PARITY NONE, SET TERMINAL
  3721. BYTESIZE 8, SET COMMAND BYTESIZE 8; that is, a way to set up an 8-bit
  3722. clean connection in a single command.
  3723. 2.5. The Services Directory
  3724. Chapter 7 ofUsing C-Kermit does not mention the ULOGIN macro,
  3725. which is used by our sample services directory, CKERMIT.KND. Unlike
  3726. UNIXLOGIN, VMSLOGIN, etc, this one is for use with systems that require
  3727. a user ID but no password. Therefore it doesn't prompt for a password
  3728. or wait for a password prompt from the remote service.
  3729. In version 7.0, the CALL macro was changed to not execute a SET MODEM
  3730. TYPE command if the given modem type was the same as the current one;
  3731. otherwise the new SET MODEM TYPE command would overwrite any
  3732. customizations that the user had made to the modem settings. Ditto for
  3733. SET LINE / SET PORT and SET SPEED.
  3734. 2.6. Closing Connections
  3735. Until version 7.0, there was never an obvious and general way to close
  3736. a connection. If a serial connection was open, it could be closed by
  3737. "set line" or "set port" (giving no device name); if a network
  3738. connection was open, it could be closed by "set host" (no host name).
  3739. In version 7.0, a new command closes the connection in an obvious and
  3740. straightforward way, no matter what the connection type:
  3741. CLOSE [ CONNECTION ]
  3742. The CLOSE command was already present, and required an operand such as
  3743. DEBUG-LOG, WRITE-FILE, etc, and so could never be given by itself. The
  3744. new CONNECTION operand is now the default operand for CLOSE, so CLOSE
  3745. by itself closes the connection, if one is open, just as you would
  3746. expect, especially if you are a Telnet or Ftp user.
  3747. Also see the description of the new SET CLOSE-ON-DISCONNECT command in
  3748. Section 2.10.
  3749. 2.7. Using C-Kermit with External Communication Programs
  3750. C-Kermit 7.0 includes a new ability to create and conduct sessions
  3751. through other communications programs. Two methods are available:
  3752. 1. Pty (pseudoterminal): The external program is run on a
  3753. "pseudoterminal", which is controlled by Kermit. This method works
  3754. with practically any external program, but it is not portable. At
  3755. this writing, it works only on some (not all) UNIX versions, and
  3756. not on any non-UNIX platforms.
  3757. 2. Pipe: The external program's standard input and output are
  3758. redirected through a "pipe" controlled by Kermit. This method is
  3759. relatively portable -- it should work across all UNIX versions, and
  3760. it also works in Windows and OS/2 -- but it is effective only when
  3761. the external program actually uses standard i/o (and many don't).
  3762. The two methods are started differently but are used the same way
  3763. thereafter.
  3764. The purpose of this feature is to let you use C-Kermit services like
  3765. file transfer, character-set translation, scripting, automatic dialing,
  3766. etc, on connections that Kermit can't otherwise make itself.
  3767. This feature is the opposite of the REDIRECT feature, in which C-Kermit
  3768. makes the connection, and redirects an external (local) command or
  3769. program over this connection. In a pty or pipe connection, C-Kermit
  3770. runs and controls a local command or program, which makes the
  3771. connection. (The same method can be used to simply to control a local
  3772. program without making a connection; see Section 2.8.)
  3773. To find out if your version of Kermit includes PTY support, type "show
  3774. features" and look for NETPTY in the alphabetical list of options. For
  3775. pipes, look for NETCMD.
  3776. The commands are:
  3777. SET NETWORK TYPE PTY or SET NETWORK TYPE PIPE
  3778. SET HOST command
  3779. where command is any interactive command. If the command does
  3780. not use standard i/o, you must use SET NETWORK TYPE PTY.
  3781. Notes:
  3782. * COMMAND is an invisible synonym for PIPE.
  3783. * The command and its arguments are case-sensitive in UNIX.
  3784. The SET NETWORK TYPE, SET HOST sequence sets the given network type for
  3785. all subsequent SET HOST commands until another SET NETWORK TYPE command
  3786. is given to change it.
  3787. You can also use the new /NETWORK-TYPE:PTY or /NETWORK-TYPE:PIPE (or
  3788. simply /PIPE or /PTY) switches on the SET HOST command itself:
  3789. SET HOST /NETWORK-TYPE:PIPE command ; These two are the same
  3790. SET HOST /PIPE command
  3791. SET HOST /NETWORK-TYPE:PTY command ; Ditto
  3792. SET HOST /PTY command
  3793. These are like SET NETWORK TYPE followed by SET HOST, except they apply
  3794. only to the connection being made and do not change the global network
  3795. type setting (see Section 1.5 about the difference between
  3796. switches and SET commands).
  3797. Include any command-line options with the command that might be needed,
  3798. as in this example where C-Kermit uses another copy of itself as the
  3799. communications program:
  3800. SET HOST /PIPE /CONNECT kermit -YQJ xyzcorp.com
  3801. IMPORTANT: In Unix, wildcards and redirectors are interpreted by the
  3802. shell. If you want to run a program with (say) SET HOST /PTY with
  3803. its i/o redirected or with wildcard file arguments, you will need to
  3804. invoke the shell too. Example:
  3805. SET HOST /PTY {sh -c "crypt < foo.x"}
  3806. SET HOST /PTY {sh -c "grep somestring *.txt"}
  3807. As usual, if you include the /CONNECT switch, SET HOST enters CONNECT
  3808. mode immediately upon successful execution of the given command.
  3809. Therefore new commands are available as a shorthand for SET HOST
  3810. /CONNECT /PTY and /PIPE:
  3811. PTY [ command ]
  3812. PIPE [ command ]
  3813. The PTY and PIPE commands work like the TELNET and RLOGIN
  3814. commands: they set up the connection (in this case, using the
  3815. given command) and then enter CONNECT mode automatically (if the
  3816. PIPE or PTY command is given without a command, it continues the
  3817. current session if one is active; otherwise it gives an error
  3818. message).
  3819. The PIPE command is named after the mechanism by which C-Kermit
  3820. communicates with the command: UNIX pipes. C-Kermit's i/o is "piped"
  3821. through the given command. Here is a typical example:
  3822. PIPE rlogin -8 xyzcorp.com
  3823. This is equivalent to:
  3824. SET HOST /PIPE rlogin -8 xyzcorp.com
  3825. CONNECT
  3826. and to:
  3827. SET HOST /PIPE /CONNECT rlogin -8 xyzcorp.com
  3828. IMPORTANT:
  3829. If you are writing a script, do not use the PIPE, PTY, TELNET,
  3830. or RLOGIN command unless you really want C-Kermit to enter
  3831. CONNECT mode at that point. Normally SET HOST is used in scripts
  3832. to allow the login and other dialogs to be controlled by the
  3833. script itself, rather than by an actively participating human at
  3834. the keyboard.
  3835. Throughput of pty and pipe connections is limited by the performance of
  3836. the chosen command or program and by the interprocess communication
  3837. (IPC) method used and/or buffering capacity of the pipe or pty, which
  3838. in turn depends on the underlying operating system.
  3839. In one trial (on SunOS 4.1.3), we observed file transfer rates over an
  3840. rlogin connection proceeding at 200Kcps for downloads, but only 10Kcps
  3841. for uploads on the same connection with the same settings (similar
  3842. disparities were noted in HP-UX). Examination of the logs revealed that
  3843. a write to the pipe could take as long as 5 seconds, whereas reads were
  3844. practically instantaneous. On the other hand, using Telnet as the
  3845. external program rather than rlogin, downloads and uploads were better
  3846. matched at about 177K each.
  3847. Most external communication programs, like C-Kermit itself, have escape
  3848. characters or sequences. Normally these begin with (or consist entirely
  3849. of) a control character. You must be sure that this control character
  3850. is not "unprefixed" when uploading files, otherwise the external
  3851. program will "escape back" to its prompt, or close the connection, or
  3852. take some other unwanted action. When in CONNECT mode, observe the
  3853. program's normal interaction rules. Of course C-Kermit's own escape
  3854. character (normally Ctrl-\) is active too, unless you have taken some
  3855. action to disable it.
  3856. On PTY connections, the underlying PTY driver is not guaranteed to be
  3857. transparent to control characters -- for example, it might expand tabs,
  3858. translate carriage returns, generate signals if it sees an interrupt
  3859. character, and so on. Similar things might happen on a PIPE connection.
  3860. For this reason, if you plan to transfer files over a PTY or PIPE
  3861. connection, tell the file sender to:
  3862. SET PREFIXING ALL
  3863. This causes all control characters to be prefixed and
  3864. transmitted as printable ASCII characters.
  3865. If the external connection program is not 8-bit clean, you should also:
  3866. SET PARITY SPACE
  3867. This causes 8-bit data to be encoded in 7 bits using single
  3868. and/or locking shifts.
  3869. And if it does not make a reliable connection (such as those made by
  3870. Telnet, Rlogin, Ssh, etc), you should:
  3871. SET STREAMING OFF
  3872. This forces C-Kermit to treat the connection as unreliable and
  3873. to engage in its normal ACK/NAK protocol for error detection and
  3874. correction, rather than "streaming" its packets, as it normally
  3875. does on a network connection ( Section 4.20).
  3876. In some cases, buffer sizes might be restricted, so you might also need
  3877. to reduce the Kermit packet length to fit; this is a trial-and-error
  3878. affair. For example, if transfers always fail with 4000-byte packets,
  3879. try 2000. If that fails too, try 1000, and so on. The commands are:
  3880. SET RECEIVE PACKET-LENGTH number
  3881. This tells the file receiver to tell the file sender the longest
  3882. packet length it can accept.
  3883. SET SEND PACKET-LENGTH number
  3884. This tells the file sender not to send packets longer than the
  3885. given length, even if the receiver says longer ones are OK. Of
  3886. course, if the receiver's length is shorter, the shorter length
  3887. is used.
  3888. If none of this seems to help, try falling back to the bare minimum,
  3889. lowest-common-denominator protocol settings:
  3890. ROBUST
  3891. No sliding windows, no streaming, no control-character
  3892. unprefixing, packet length 90.
  3893. And then work your way back up by trial and error to get greater
  3894. throughput.
  3895. Note that when starting a PIPE connection, and the connection program
  3896. (such as telnet or rlogin) prints some greeting or information messages
  3897. before starting the connection, these are quite likely to be printed
  3898. with a stairstep effect (linefeed without carriage return). This is
  3899. because the program is not connected with the UNIX terminal driver;
  3900. there's not much Kermit can do about it. Once the connection is made,
  3901. everything should go back to normal. This shouldn't happen on a PTY
  3902. connection because a PTY is, indeed, a terminal.
  3903. On a similar note, some connection programs (like Solaris 2.5 rlogin)
  3904. might print lots of error messages like "ioctl TIOCGETP: invalid
  3905. argument" when used through a pipe. They are annoying but usually
  3906. harmless. If you want to avoid these messages, and your shell allows
  3907. redirection of stderr, you can redirect stderr in your pipe command, as
  3908. in this example where the user's shell is bash:
  3909. PIPE rlogin xyzcorp.com 2> /dev/null
  3910. Or use PTY rather than PIPE, since PTY is available on Solaris.
  3911. 2.7.0. C-Kermit over tn3270 and tn5250
  3912. Now you can make a connection from C-Kermit "directly" to an IBM
  3913. mainframe and transfer files with it, assuming it has Kermit-370
  3914. installed. Because tn3270 is neither 8-bit clean nor transparent to
  3915. control characters, you must give these commands:
  3916. SET PREFIXING ALL ; Prefix all control characters
  3917. SET PARITY SPACE ; Telnet connections are usually not 8-bit clean
  3918. and then:
  3919. SET HOST /PTY /CONNECT tn3270 abccorp.com
  3920. or simply:
  3921. pty tn3270 abccorp.com
  3922. SET HOST /PIPE does not work in this case, at least not for file
  3923. transfer. File transfer does work, however, with SET HOST /PTY,
  3924. provided you use the default packet length of 90 bytes; anything longer
  3925. seems to kill the session.
  3926. You can also make connections to IBM AS/400 computers if you have a
  3927. tn5250 program installed:
  3928. pty tn5250 hostname
  3929. In this case, however, file transfer is probably not in the cards since
  3930. nobody has ever succeeded in writing a Kermit program for the AS/400.
  3931. Hint:
  3932. define tn3270 {
  3933. check pty
  3934. if fail end 1 Sorry - no PTY support...
  3935. pty tn3270 \%*
  3936. }
  3937. Similarly for tn5250. Note that CHECK PTY and CHECK PIPE can be used in
  3938. macros and scripts to test whether PTY or PIPE support is available.
  3939. 2.7.1. C-Kermit over Telnet
  3940. Although C-Kermit includes its own Telnet implementation, you might
  3941. need to use an external Telnet program to make certain connections;
  3942. perhaps because it has access or security features not available in
  3943. C-Kermit itself. As noted above, the only precautions necessary are
  3944. usually:
  3945. SET PREFIXING ALL ; Prefix all control characters
  3946. SET PARITY SPACE ; Telnet connections might not be 8-bit clean
  3947. and then:
  3948. SET HOST /PTY (or /PIPE) /CONNECT telnet abccorp.com
  3949. or, equivalently:
  3950. PTY (or PIPE) telnet abccorp.com
  3951. 2.7.2. C-Kermit over Rlogin
  3952. C-Kermit includes its own Rlogin client, but this can normally be used
  3953. only if you are root, since the rlogin TCP port is privileged. But ptys
  3954. and pipes let you make rlogin connections with C-Kermit through your
  3955. computer's external rlogin program, which is normally installed as a
  3956. privileged program:
  3957. SET PREFIXING ALL
  3958. and then:
  3959. SET HOST /PTY (or /PIPE) /CONNECT rlogin -8 abccorp.com
  3960. or, equivalently:
  3961. PTY (or PIPE) rlogin -8 abccorp.com
  3962. The "-8" option to rlogin enables transmission of 8-bit data. If this
  3963. is not available, then include SET PARITY SPACE if you intend to
  3964. transfer files.
  3965. Note that the normal escape sequence for rlogin is Carriage Return
  3966. followed by Tilde (~), but only when the tilde is followed by certain
  3967. other characters; the exact behavior depends on your rlogin client, so
  3968. read its documentation.
  3969. 2.7.3. C-Kermit over Serial Communication Programs
  3970. Ptys and pipes also let you use programs that make serial connections,
  3971. such as cu or tip. For example, C-Kermit can be used through cu to make
  3972. connections that otherwise might not be allowed, e.g. because C-Kermit
  3973. is not installed with the required write permissions to the dialout
  3974. device and the UUCP lockfile directory.
  3975. Suppose your UUCP Devices file contains an entry for a serial device
  3976. tty04 to be used for direct connections, but this device is protected
  3977. against you (and Kermit when you run it). In this case you can:
  3978. SET CONTROL PREFIX ALL
  3979. PTY (or PIPE) cu -l tty04
  3980. (Similarly for dialout devices, except then you also need to include
  3981. the phone number in the "cu" command.)
  3982. As with other communication programs, watch out for cu's escape
  3983. sequence, which is the same as the rlogin program's: Carriage Return
  3984. followed by Tilde (followed by another character to specify an action,
  3985. like "." for closing the connection and exiting from cu).
  3986. 2.7.4. C-Kermit over Secure Network Clients
  3987. DISCLAIMER: There are laws in the USA and other countries regarding
  3988. use, import, and/or export of encryption and/or decryption or other
  3989. forms of security software, algorithms, technology, and intellectual
  3990. property. The Kermit Project attempts to follow all known statutes,
  3991. and neither intends nor suggests that Kermit software can or should
  3992. be used in any way, in any location, that circumvents any
  3993. regulations, laws, treaties, covenants, or other legitimate canons
  3994. or instruments of law, international relations, trade, ethics, or
  3995. propriety.
  3996. For secure connections or connections through firewalls, C-Kermit 7.0
  3997. can be a Kerberos, SRP, and/or SOCKS client when built with the
  3998. appropriate options and libraries. But other application-level security
  3999. acronyms and methods -- SSH, SSL, SRP, TLS -- pop up at an alarming
  4000. rate and are (a) impossible to keep up with, (b) usually mutually
  4001. incompatible, and (c) have restrictions on export or redistribution and
  4002. so cannot be included in C-Kermit itself.
  4003. However, if you have a secure text-based Telnet (or other) client that
  4004. employs one of these security methods, you can use C-Kermit "through"
  4005. it via a pty or pipe.
  4006. 2.7.4.1. SSH
  4007. C-Kermit does not and can not incorporate SSH due to licensing, patent,
  4008. and USA export law restrictions.
  4009. The UNIX SSH client does not use standard input/output, and therefore
  4010. can be used only by Kermit's PTY interface, if one is present. The
  4011. cautions about file transfer, etc, are the same as for Rlogin. Example:
  4012. SET PREFIXING ALL
  4013. PTY ssh XYZCORP.COM
  4014. Or, for a scripted session:
  4015. SET PREFIXING ALL
  4016. SET HOST /PTY ssh XYZCORP.COM
  4017. Hint:
  4018. define ssh {
  4019. check pty
  4020. if fail end 1 Sorry - no PTY support...
  4021. pty ssh \%*
  4022. }
  4023. 2.7.4.2. SSL
  4024. Secure Sockets Layer (SSL) is another TCP/IP security overlay, this one
  4025. designed by and for Netscape. An SSL Telnet client is available for
  4026. UNIX from the University of Queensland. More info at:
  4027. http://www.psy.uq.oz.au/~ftp/Crypto/
  4028. Interoperability with C-Kermit is unknown. C-Kermit also includes its
  4029. own built-in SSL/TLS support, but it is not exportable.
  4030. 2.7.4.3. SRP
  4031. SRP(TM) is Stanford University's Secure Remote Password protocol. An
  4032. SRP Telnet client is available from Stanford:
  4033. http://srp.stanford.edu/srp/
  4034. Stanford's SRP Telnet client for UNIX has been tested on SunOS and
  4035. works fine with C-Kermit, as described in Section 2.7.1, e.g.
  4036. SET PREFIX ALL
  4037. PTY (or PIPE) srp-telnet xenon.stanford.edu
  4038. C-Kermit itself can be built as an SRP Telnet client on systems that
  4039. have libsrp.a installed; the C-Kermit support code, however, may not be
  4040. exported outside the USA or Canada.
  4041. 2.7.4.4. SOCKS
  4042. C-Kermit can be built as a SOCKS-aware client on systems that have a
  4043. SOCKS library. See section 8.1.1 of theckccfg.txt file.
  4044. C-Kermit 7.0 can also be run over SOCKSified Telnet or rlogin clients
  4045. with SET NETWORK TYPE COMMAND. Suppose the Telnet program on your
  4046. system is SOCKS enabled but C-Kermit is not. Make Kermit connections
  4047. like this:
  4048. SET PREFIX ALL
  4049. PTY (or PIPE) telnet zzz.com
  4050. 2.7.4.5. Kerberos
  4051. UNIX C-Kermit can be built with MIT Kerberos IV or V authentication and
  4052. encryption. Instructions are available in aseparate document.
  4053. Additional modules are required that can not be exported from the USA
  4054. to any country except Canada, by US law.
  4055. If you have Kerberos installed but you don't have a Kerberized version
  4056. of C-Kermit, you can use ktelnet as C-Kermit's external communications
  4057. program to make secure connections without giving up C-Kermit's
  4058. services:
  4059. SET PREFIX ALL
  4060. PTY (or PIPE) ktelnet cia.gov
  4061. 2.8. Scripting Local Programs
  4062. If your version of Kermit has PTY support built in, then any text-based
  4063. program can be invoked with SET HOST /PTY or equivalent command and
  4064. controlled using the normal sequence of OUTPUT, INPUT, IF SUCCESS
  4065. commands (this is the same service that is provided by the 'expect'
  4066. program, but controlled by the Kermit script language rather than Tcl).
  4067. When PTY service is not available, then any program that uses standard
  4068. input and output can be invoked with SET HOST /PIPE.
  4069. Here's an example in which we start an external Kermit program, wait
  4070. for its prompt, give it a VERSION command, and then extract the numeric
  4071. version number from its response:
  4072. set host /pty kermit -Y
  4073. if fail stop 1 {Can't start external command}
  4074. input 10 C-Kermit>
  4075. if fail stop 1 {No C-Kermit> prompt}
  4076. output version\13
  4077. input 10 {Numeric: }
  4078. if fail stop 1 {No match for "Numeric:"}
  4079. clear input
  4080. input 10 \10
  4081. echo VERSION = "\fsubstr(\v(input),1,6)"
  4082. output exit\13
  4083. This technique could be used to control any other interactive program,
  4084. even those that do screen formatting (like Emacs or Vi), if you can
  4085. figure out the sequence of events. If your Kermit program doesn't have
  4086. PTY support, then the commands are restricted to those using standard
  4087. i/o, including certain shells, interactive text-mode "hardcopy" editors
  4088. like ex, and so on.
  4089. If you are using the PTY interface, you should be aware that it runs
  4090. the given program or command directly on the pty, without any
  4091. intervening shell to interpret metacharacters, redirectors, etc. If you
  4092. need this sort of thing, include the appropriate shell invocation as
  4093. part of your command; for example:
  4094. pty echo *
  4095. just echoes "*"; whereas:
  4096. pty ksh -c "echo *"
  4097. echoes all the filenames that ksh finds matching "*".
  4098. Similarly for redirection:
  4099. set host /pty ksh -c "cat > foo" ; Note: use shell quoting rules here
  4100. set transmit eof \4
  4101. transmit bar
  4102. And for that matter, for built-in shell commands:
  4103. set host /pty ksh -c "for i in *; do echo $i; done"
  4104. The PIPE interface, on the other hand, invokes the shell automatically,
  4105. so:
  4106. pipe echo *
  4107. prints filenames, not "*".
  4108. 2.9. X.25 Networking
  4109. X.25 networking is documented inUsing C-Kermit, 2nd Edition. When
  4110. the book was published, X.25 was available only in SunOS, Solaris, and
  4111. Stratus VOS. Unlike TCP/IP, X.25 APIs are not standardized; each
  4112. vendor's X.25 libraries and services (if they have them at all) are
  4113. unique.
  4114. This section describes new additions.
  4115. 2.9.1. IBM AIXLink/X.25 Network Provider Interface for AIX
  4116. Support for X.25 was added via IBM's Network Provider Interface (NPI),
  4117. AIXLink/X.25 1.1, to the AIX 4.x version of C-Kermit 7.0.
  4118. Unfortunately, AIXLink/X.25 is a rather bare-bones facility, lacking in
  4119. particular any form of PAD support (X.3, X.28, X.29). Thus, the AIX
  4120. version of C-Kermit, when built to include X.25 networking, has neither
  4121. a PAD command, nor a SET PAD command. The same is true for the
  4122. underlying AIX system: no PAD support. Thus it is not possible to have
  4123. an interactive shell session over an X.25 connection into an AIX system
  4124. (as far as we know), even from X.25-capable Kermit versions (such as
  4125. Solaris or VOS) that do include PAD support.
  4126. Thus the X.25 capabilities in AIX C-Kermit are limited to peer-to-peer
  4127. connections, e.g. from a C-Kermit client to a C-Kermit server. Unlike
  4128. the Solaris, SunOS, and VOS versions, the AIX version can accept
  4129. incoming X.25 connections:
  4130. set network type x.25
  4131. if fail stop 1 Sorry - no X.25 support
  4132. ; Put any desired DISABLE or ENABLE or SET commands here.
  4133. set host /server *
  4134. if fail stop 1 X.25 "set host *" failed
  4135. And then access it from the client as follows:
  4136. set network type x.25
  4137. if fail stop 1 Sorry - no X.25 support
  4138. set host xxxxxxx ; Specify the X.25/X.121 address
  4139. if fail stop 1 Can't open connection
  4140. And at this point the client can use the full range of client commands:
  4141. SEND, GET, REMOTE xxx, FINISH, BYE.
  4142. The AIX version also adds two new variables:
  4143. \v(x25local_nua)
  4144. The local X.25 address.
  4145. \v(x25remote_nua)
  4146. The X.25 address of the host on the other end of the connection.
  4147. C-Kermit's AIX X.25 client has not been tested against anything other
  4148. than a C-Kermit X.25 server on AIX. It is not known if it will
  4149. interoperate with C-Kermit servers on Solaris, SunOS, or VOS.
  4150. To make an X.25 connection from AIX C-Kermit, you must:
  4151. set x25 call-user-data xxxx
  4152. where xxxx can be any even-length string of hexadecimal digits, e.g.
  4153. 123ABC.
  4154. 2.9.2. HP-UX X.25
  4155. Although C-Kermit presently does not include built-in support for HP-UX
  4156. X.25, it can still be used to make X.25 connections as follows: start
  4157. Kermit and tell it to:
  4158. set prefixing all
  4159. set parity space
  4160. pty padem address
  4161. This should work in HP-UX 9.00 and later (see Section 2.7). If you
  4162. have an earlier HP-UX version, or the PTY interface doesn't work or
  4163. isn't available, try:
  4164. set prefixing all
  4165. set parity space
  4166. pipe padem address
  4167. Failing that, use Kermit to telnet to localhost and then after logging
  4168. back in, start padem as you would normally do to connect over X.25.
  4169. 2.10. Additional Serial Port Controls
  4170. C-Kermit 7.0 adds the following commands for greater control over
  4171. serial ports. These commands are available only in C-Kermit versions
  4172. whose underlying operating systems provide the corresponding services
  4173. (such as POSIX and UNIX System V), and even then their successful
  4174. operation depends on the capabilities of the specific device and
  4175. driver.
  4176. SET DISCONNECT { ON, OFF }
  4177. On a SET LINE or SET PORT connection with SET CARRIER ON or
  4178. AUTO, if the carrier signal drops during the connection,
  4179. indicating that the connection has been lost, and C-Kermit
  4180. notices it, this setting governs what happens next. With SET
  4181. DISCONNECT OFF, which is consistent with previous behavior, and
  4182. therefore the default, C-Kermit continues to keep the device
  4183. open and allocated. With SET DISCONNECT ON, C-Kermit
  4184. automatically closes and releases the device when it senses a
  4185. carrier on-to-off transition, thus allowing others to use it.
  4186. However, it remains the default device for i/o (DIAL, REDIAL,
  4187. INPUT, SEND, CONNECT, etc), so if a subsequent i/o command is
  4188. given, the device is reopened if it is still available. When it
  4189. has been automatically closed in this manner, SHOW
  4190. COMMUNICATIONS puts "(closed)" after its name, and in UNIX, the
  4191. lockfile disappears -- both from SHOW COMM and from the lockfile
  4192. directory itself. Synonym: SET CLOSE-ON-DISCONNECT.
  4193. SET EXIT ON-DISCONNECT { ON, OFF }
  4194. Like DISCONNECT, but makes the program exit if a connection
  4195. drops.
  4196. Note that SET CLOSE-ON-DISCONNECT and SET EXIT ON-DISCONNECT apply only
  4197. to connections that drop; they do not apply to connections that can't
  4198. be made in the first place. For example, they have no effect when a SET
  4199. LINE, SET HOST, TELNET, or DIAL command fails.
  4200. HANGUP
  4201. If [CLOSE-ON-]DISCONNECT is ON, and the HANGUP command is given
  4202. on a serial device, and the carrier signal is no longer present
  4203. after the HANGUP command, the device is closed and released.
  4204. SET PARITY HARDWARE { EVEN, ODD }
  4205. Unlike SET PARITY { EVEN, ODD, MARK, SPACE }, which selects 7
  4206. data bits plus the indicated kind of parity (to be done in
  4207. software by Kermit itself), SET PARITY HARDWARE selects 8 data
  4208. bits plus even or odd parity, to be done by the underlying
  4209. hardware, operating system, or device driver. This command is
  4210. effective only with a SET LINE or SET PORT device. That is, it
  4211. has no effect in remote mode, nor on network connections. There
  4212. is presently no method for selecting 8 data bits plus mark or
  4213. space parity. If hardware parity is in effect, the variable
  4214. \v(hwparity) is set to "even" or "odd". Note: some platforms
  4215. might also support settings of SPACE, MARK, or NONE.
  4216. SET STOP-BITS { 1, 2 }
  4217. This tells the number of 1-bits to insert after an outbound
  4218. character's data and parity bits, to separate it from the next
  4219. character. Normally 1. Choosing 2 stop bits should do no harm,
  4220. but will slow down serial transmission by approximately 10
  4221. percent. Historically, 2 stop bits were used with Teletypes (at
  4222. 110 bps or below) for print-head recovery time. There is
  4223. presently no method for choosing any number of stop bits besides
  4224. 1 and 2.
  4225. SET SERIAL [ dps ]
  4226. dps stands for Data-bits, Parity, Stop-bits. This is the
  4227. notation familiar to many people for serial port configuration:
  4228. 7E1, 8N1, 7O2, etc. The data bits number also becomes the
  4229. TERMINAL BYTESIZE setting. The second character is E for Even, O
  4230. for Odd, M for Mark, S for Space, or N for None. The list of
  4231. available options depends on the capabilities of the specific
  4232. platform. If dps is omitted, 8N1 is used. Type "set serial ?"
  4233. for a list of available choices. Examples:
  4234. SET SERIAL 7E1
  4235. Equivalent to SET PARITY EVEN, SET STOP-BITS 1, SET TERM
  4236. BYTE 7.
  4237. SET SERIAL 8N1
  4238. Equivalent to SET PARITY NONE, SET STOP-BITS 1, SET TERM
  4239. BYTE 8.
  4240. SET SERIAL 7E2
  4241. Equivalent to SET PARITY EVEN and SET STOP-BITS 2, SET
  4242. TERM BYTE 7.
  4243. SET SERIAL 8E2
  4244. Same as SET PARITY HARDWARE EVEN, SET STOP-BITS 2, SET
  4245. TERM BYTE 8.
  4246. SET SERIAL
  4247. Same as SET PARITY NONE and SET STOP-BITS 1, SET TERM BYTE
  4248. 8.
  4249. Notes:
  4250. * The SET SERIAL xx2 options are available only in Kermit versions
  4251. where the SET PARITY HARDWARE command is also available. (SHOW
  4252. FEATURES includes "HWPARITY" in its options list.)
  4253. * The SET SERIAL 7xx and 8N1 options affect the software parity
  4254. setting, even for network connections.
  4255. * As noted in the manual, selecting 8 data bits does not give you
  4256. 8-bit terminal sessions in CONNECT mode unless you also SET
  4257. TERMINAL BYTESIZE 8. The default terminal bytesize remains 7, to
  4258. protect against the situation where the remote host is generating
  4259. parity but you don't know about it. If the terminal bytesize was 8
  4260. by default and you CONNECTed to such a host, you would see only
  4261. garbage on your screen.
  4262. * If you do not give a SET STOP-BITS or SET SET SERIAL command,
  4263. C-Kermit does not attempt to set the device's stop bits; instead,
  4264. it uses whatever setting the device uses when not given explicit
  4265. instructions about stop bits.
  4266. SHOW COMMUNICATIONS displays the current settings. Stop bits and
  4267. hardware parity are shown only for SET PORT / SET LINE (serial)
  4268. devices, since they do not apply to network connections or to remote
  4269. mode. STOP-BITS is shown as "(default)" if you have not given an
  4270. explicit SET STOP-BITS or SET SERIAL command.
  4271. The \v(serial) variable shows the SET SERIAL setting (8N1, 7E1, etc).
  4272. 2.11. Getting Access to the Dialout Device
  4273. This section is for UNIX only; note the special words about QNX at
  4274. the end. Also see Section 2.0 for SET LINE switches,
  4275. particularly the /SHARE switch for VMS only.
  4276. C-Kermit does its best to obey the UUCP lockfile conventions of each
  4277. platform (machine, operating system, OS version) where it runs, if that
  4278. platform uses UUCP.
  4279. But simply obeying the conventions is often not good enough, due to the
  4280. increasing likelihood that a particular serial device might have more
  4281. than one name (e.g. /dev/tty00 and /dev/term/00 are the same device in
  4282. Unixware 7; /dev/cua and /dev/cufa are the same device in NeXTSTEP),
  4283. plus the increasingly widespread use of symlinks for device names, such
  4284. as /dev/modem.
  4285. C-Kermit 7.0 goes to greater lengths than previous versions to
  4286. successfully interlock with other communications program (and other
  4287. instances of Kermit itself); for example, by:
  4288. * Creation of dual lockfiles whenever a symlink is used; one for the
  4289. link name and one for the real name.
  4290. * Creation of dual lockfiles in HP-UX according to HP rules.
  4291. * Creation of dual uppercase/lowercase lockfile names in SCO
  4292. UNIX/ODT/OSR5.
  4293. * The use of ttylock() in versions of AIX where it works.
  4294. * The use, wherever possible, of lockfile names based on
  4295. inode/major/minor device number rather than device name.
  4296. See theckuins.txt andckubwr.txt files for details.
  4297. QNX is almost unique among UNIX varieties in having no UUCP programs
  4298. nor UUCP-oriented dialout-device locking conventions. QNX does,
  4299. however, allow a program to get the device open count. This can not be
  4300. a reliable form of locking unless all applications do it (and they
  4301. don't), so by default, Kermit uses this information only for printing a
  4302. warning message such as:
  4303. C-Kermit>set line /dev/ser1
  4304. WARNING - "/dev/ser1" looks busy...
  4305. However, if you want to use it as a lock, you can do so with:
  4306. SET QNX-PORT-LOCK { ON, OFF }
  4307. QNX-PORT-LOCK is OFF by default; if you set in ON, C-Kermit fails to
  4308. open any dialout device when its open count indicates that another
  4309. process has it open. SHOW COMM (in QNX only) displays the setting, and
  4310. if you have a port open, it also shows the current open count (with
  4311. C-Kermit's own access always counting as 1).
  4312. 2.12. The Connection Log
  4313. C-Kermit 7.0 adds the ability to log connections, so you can see where
  4314. you've been and have a record of calls you've made. A connection is
  4315. defined as any communications session that is begun by SET LINE, SET
  4316. PORT, DIAL, SET HOST, TELNET, or RLOGIN. Connections are not logged
  4317. unless you request it; the command is:
  4318. LOG CX [ filename [ { NEW, APPEND } ] ]
  4319. Enables logging of connections in the given file. If the
  4320. trailing { NEW, APPEND } keyword is omitted, the file is opened
  4321. for appending; i.e. new records are written to the end. If NEW
  4322. is specified, a new file is created; if a file of the same name
  4323. already existed, it is overwritten. If the filename is omitted,
  4324. CX.LOG in your home (login) directory is used (note: uppercase).
  4325. To accept all defaults, just use "log connections" (or "l c" for
  4326. short). Synonym: LOG CONNECTIONS.
  4327. CLOSE CX-LOG
  4328. This closes the connection log if it was open. (Note, the CLOSE
  4329. CONNECTION command closes the connection itself).
  4330. SHOW CX
  4331. This shows your current connection, if any, including the
  4332. elapsed time (since you opened it). Synonym: SHOW CONNECTION.
  4333. \v(cx_time)
  4334. This variable shows the elapsed time of your current connection,
  4335. or if there is no current connection, of your most recent
  4336. connection, of if there have been no connections, 0.
  4337. The connection contains one line per connection, of the form:
  4338. yyyymmdd hh:mm:ss username pid p=v [ p=v [ ... ] ]
  4339. where the timestamp (in columns 1-18) shows when the connection was
  4340. made; username is the login identity of the person who made the
  4341. connection; pid is Kermit's process ID when it made the connection. The
  4342. p's are parameters that depend on the type of connection, and the v's
  4343. are their values:
  4344. T = Connection Type (TCP, SERIAL, DIAL, DECNET, etc).
  4345. H = The name of the Host from which the connection was made.
  4346. N = Destination phone Number or Network host name or address.
  4347. D = Serial connections only: Device name.
  4348. O = Dialed calls only: Originating country code & area code if known.
  4349. E = Elapsed time in hh:mm:ss format (or hhh:mm:ss, etc).
  4350. If you always want to keep a connection log, simply add:
  4351. log connections
  4352. to your C-Kermit customization file. Note, however, that if you make a
  4353. lot of connections, your CX.LOG will grow and grow. You can handle this
  4354. by adding a "logrotate" procedure like the following to your
  4355. customization file, before the "log connections" command:
  4356. define LOGROTATE { ; Define LOGROTATE macro
  4357. local \%i \%m \%d \%n \%f MAX
  4358. def MAX 4 ; How many months to keep
  4359. if not def \%1 - ; No argument given
  4360. end 1 \%0: No filename given
  4361. if not = 1 \ffiles(\%1) - ; Exactly 1 file must match
  4362. end 1 \%0: \%1 - File not found
  4363. .\%d := \fsubstr(\fdate(\%1),1,6) ; Arg OK - get file year & month
  4364. if = \%d - ; Compare file year & month
  4365. \fsubstr(\v(ndate),1,6) - ; with current year & month
  4366. end 0 ; Same year & month - done
  4367. rename \%1 \%1.\%d ; Different - rename file
  4368. .\%n := \ffiles(\%1.*) ; How many old files
  4369. if < \%n \m(MAX) end 0 ; Not enough to rotate
  4370. .\%m := \%1.999999 ; Initial compare string
  4371. for \%i 1 \%n 1 { ; Loop thru old logs
  4372. .\%f := \fnextfile() ; Get next file name
  4373. if llt \%f \%m .\%m := \%f ; If this one older remember it
  4374. }
  4375. delete \%m ; Delete the oldest one
  4376. }
  4377. log connections ; Now open the (possibly new) log
  4378. logrotate \v(home)CX.LOG ; Run the LOGROTATE macro
  4379. As you can see, this compares the yyyymm portion of the modification
  4380. date (\fdate()) of the given file (\%1) with the current yyyymm. If
  4381. they differ, the current file has the yyyymm suffix (from its most
  4382. recent modification date) appended to its name. Then we search through
  4383. all other such files, find the oldest one, and delete it. Thus the
  4384. current log, plus the logs from the most recent four months, are kept.
  4385. This is all done automatically every time you start C-Kermit.
  4386. On multiuser systems, it is possible to keep a single, shared,
  4387. system-wide connection log, but this is not recommended since (a) it
  4388. requires you keep a publicly write-accessible logfile (a glaring target
  4389. for mischief), and (b) it would require each user to log to that file
  4390. and not disable logging. A better method for logging connections, in
  4391. UNIX at least, is syslogging (seeckuins.txt Section 15 and
  4392. Section 4.2 of theIKSD Administration Guide for details).
  4393. 2.13. Automatic Connection-Specific Flow Control Selection
  4394. Beginning in C-Kermit 7.0, the appropriate flow-control method for each
  4395. connection type is kept in a table, for example:
  4396. Remote: NONE
  4397. Modem: RTS/CTS
  4398. Direct-Serial: NONE
  4399. TCPIP: NONE
  4400. The size of the table and values for each connection type can vary from
  4401. platform to platform. Type "set flow ?" for a list of available
  4402. flow-control types.
  4403. The table is used to automatically select the appropriate kind of flow
  4404. control whenever you make a connection. You can display the table with:
  4405. SHOW FLOW-CONTROL
  4406. The defaults are as follows:
  4407. Remote:
  4408. NONE or XON/XOFF. This is because C-Kermit is not allowed to
  4409. find out what type of connection the incoming user has (*). No
  4410. kind of flow control will work on every kind of connection,
  4411. including (unexpectedly) KEEP, which we would have liked to use,
  4412. but not turning off flow control at the remote end during file
  4413. transfer on TCP/IP connections is fatal to the transfer (except
  4414. in VMS and HP-UX, where it must be set to Xon/Xoff!) Therefore
  4415. if you are dialing in to a serial port on a server (UNIX or VMS)
  4416. where C-Kermit is running, you will need to tell C-Kermit to
  4417. "set flow keep" before transferring files (assuming the modem
  4418. and port are configured correctly by the system administrator;
  4419. otherwise you'll need to give a specific kind of flow control,
  4420. e.g. "set flow xon/xoff"), so in this case C-Kermit will not
  4421. disable flow control, as it must do when you are coming via
  4422. Telnet (directly or through a terminal server, except on VMS and
  4423. HP-UX).
  4424. Modem:
  4425. This applies when you dial out with a modem. In this case, the
  4426. MODEM FLOW-CONTROL setting takes affect after the SET FLOW
  4427. setting, so it can pick the most appropriate flow control for
  4428. the combination of the particular modem and the
  4429. computer/port/driver that is dialing.
  4430. Direct-Serial:
  4431. The default here is NONE because C-Kermit has no way of knowing
  4432. what kind of flow control, if any, is or can be done by the
  4433. device at the other end of the connection. RTS/CTS would be a
  4434. bad choice here, because if the CTS signal is not asserted, the
  4435. connection will hang. And since direct connections are often
  4436. made with 3-wire cables, there is a good chance the CTS signal
  4437. will not be received.
  4438. TCPIP:
  4439. NONE, since TCP and IP provide their own flow control
  4440. transparently to the application, except in VMS, where Xon/Xoff
  4441. is the default due to the requirements of the VMS TCP/IP
  4442. products.
  4443. Other networks:
  4444. NONE, since networks should provide their flow control
  4445. transparently to the application.
  4446. (*) This is possibly the worst feature of UNIX, VMS, and other
  4447. platforms where C-Kermit runs. If C-Kermit was able to ask the
  4448. operating system what kind of connection it had to the user, it could
  4449. set up many things for you automatically.
  4450. You can modify the default-flow-control table with:
  4451. SET FLOW-CONTROL /xxx { NONE, KEEP, RTS/CTS, XON/XOFF, ... }
  4452. where "xxx" is the connection type, e.g.
  4453. SET FLOW /REMOTE NONE
  4454. SET FLOW /DIRECT RTS/CTS
  4455. If you leave out the switch, SET FLOW works as before, choosing the
  4456. flow control method to be used on the current connection:
  4457. SET FLOW XON/XOFF
  4458. Thus, whenever you make a connection with SET PORT, SET LINE, DIAL, SET
  4459. HOST, TELNET, RLOGIN, etc, an appropriate form of flow control is
  4460. selected automatically. You can override the automatic selection with a
  4461. subsequent SET FLOW command, such as SET FLOW NONE (no switch
  4462. included).
  4463. The flow control is changed automatically too when you give a SET MODEM
  4464. TYPE command. For example, suppose your operating system (say Linux)
  4465. supports hardware flow control (RTS/CTS). Now suppose you give the
  4466. following commands:
  4467. set line /dev/ttyS2 ; Automatically sets flow to NONE
  4468. set modem type usr ; Automatically sets flow to RTS/CTS
  4469. set modem type rolm ; Doesn't support RTS/CTS so now flow is XON/XOFF
  4470. IMPORTANT: This new feature tends to make the order of SET LINE/HOST
  4471. and SET FLOW commands matter, where it didn't before. For example, in
  4472. VMS:
  4473. SET FLOW KEEP
  4474. SET LINE TTA0:
  4475. the SET LINE undoes the SET FLOW KEEP command; the sequence now must
  4476. be:
  4477. SET FLOW /DIRECT KEEP
  4478. SET LINE TTA0:
  4479. or:
  4480. SET LINE TTA0:
  4481. SET FLOW KEEP
  4482. 2.14. Trapping Connection Establishment and Loss
  4483. If you define a macro called ON_OPEN, it is executed any time that a
  4484. SET LINE, SET PORT, SET HOST, TELNET, RLOGIN or similar command
  4485. succeeds in opening a connection. The argument is the host or device
  4486. name (as shown by SHOW COMMUNICATIONS, and the same as \v(line)). This
  4487. macro can be used for all sorts of things, like automatically setting
  4488. connection- or host-specific parameters when the connection is opened.
  4489. Example:
  4490. def ON_OPEN {
  4491. switch \%1 {
  4492. :abccorp.com, set reliable off, break
  4493. :xyzcorp.com, set receive packet-length 1000, break
  4494. etc etc...
  4495. }
  4496. }
  4497. If you define a macro called ON_CLOSE, it will be executed any time
  4498. that a SET LINE, SET PORT, SET HOST, TELNET, RLOGIN or any other kind
  4499. of connection that C-Kermit has made is closed, either by the remote or
  4500. by a local CLOSE, HANGUP, or EXIT command or other local action, such
  4501. as when a new connection is opened before an old one was explicitly
  4502. closed.
  4503. As soon as C-Kermit notices the connection has been closed, the
  4504. ON_CLOSE macro is invoked at (a) the top of the command parsing loop,
  4505. or (b) when a connection is closed implicitly by a command such as SET
  4506. LINE that closes any open connection prior to making a new connection,
  4507. or (c) when C-Kermit closes an open connection in the act of exiting.
  4508. The ON_CLOSE macro was inspired by the neverending quest to unite
  4509. Kermit and SSH. In this case using the "tunnel" mechanism:
  4510. def TUNNEL { ; \%1 = host to tunnel to
  4511. local \%p
  4512. if not def \%1 stop 1
  4513. assign tunnelhost \%1 ; Make global copy
  4514. undef on_close
  4515. set macro error off
  4516. close connection ; Ignore any error
  4517. open !read tunnel start \%1
  4518. read \%p ; Get port number
  4519. if fail stop 1 Tunnel failure: \%1
  4520. close read
  4521. if fail stop 1 Tunnel failure: \%1 ; See Section 4.2.8.1
  4522. assign on_close { ; Set up close handler
  4523. echo Closing tunnel: \m(tunnelhost)
  4524. !tunnel stop \m(tunnelhost)
  4525. undef on_close
  4526. }
  4527. set host localhost:\%p /telnet
  4528. if success end 0
  4529. undef on_close
  4530. stop 1 Connection failure: \%1
  4531. }
  4532. In this case, when the connection stops, we also need to shut down the
  4533. tunnel, even if it is at a later time after TUNNEL has finished
  4534. executing. This way we can escape back, reconnect, transfer files, and
  4535. so on until the connection is broken by logging out from the remote, or
  4536. by explicitly closing it, or by EXITing from C-Kermit, at which time
  4537. the tunnel is shut down.
  4538. When the connection is closed, no matter how, the ON_CLOSE macro
  4539. executes and then undefines (destroys) itself, since we don't want to
  4540. be closing tunnels in the future when we close subsequent connections.
  4541. Other such tricks can be imagined, including ending ON_CLOSE with a
  4542. STOP command to force the command stack to be peeled all the way back
  4543. to the top, for example in a deeply nested script that depends on the
  4544. connection being open:
  4545. def on_close { stop 1 CONNECTION LOST }
  4546. When C-Kermit invokes the ON_CLOSE macro, it supplies one argument
  4547. (\%1): the reason the connection was closed as a number, one of the
  4548. following:
  4549. 2 - Fatal failure to negotiate a required item on a network connection.
  4550. 1 - Closed by C-Kermit command.
  4551. 0 - All others (normally closed by remote).
  4552. which may be used for any purpose; for example, to add a comment to the
  4553. connection log:
  4554. def on_close {
  4555. local \%m
  4556. if not open cx end 0
  4557. switch \%1 {
  4558. :0, .\%m = Closed by remote, break
  4559. :1, .\%m = Closed by me, break
  4560. :2, .\%m = Network protocol negotiation failure, break
  4561. }
  4562. if def \%m writeln cx {# \%m}
  4563. }
  4564. 2.15. Contacting Web Servers with the HTTP Command
  4565. C-Kermit 7.0 (at this writing, the UNIX version only) supports direct
  4566. contact and interaction with Web servers via HTTP 1.0 protocol. To make
  4567. a connection, use Kermit's normal method for making a TCP/IP
  4568. connection, but specify the HTTP port:
  4569. SET HOST host http [ switches ]
  4570. where host is the IP hostname or address, and http is the name of the
  4571. TCP port for the Web server. Relevant switches include:
  4572. /RAW
  4573. Treat the connection as a transparent binary pipe. This switch
  4574. may be required if a port other than 'http' is used.
  4575. /SSL
  4576. Make an secure private connection with SSL (only if SSL support
  4577. is included in your version of Kermit). In this case the port
  4578. name might need to be https rather than http, e.g. "set host
  4579. secureserver.xyzcorp.com https /ssl".
  4580. /TLS
  4581. Make an secure private connection with TLS (only if TLS support
  4582. is included in your version of Kermit). In this case the port
  4583. name would be https rather than http.
  4584. Then you can issue an HTTP command. In most cases, the server closes
  4585. the connection when the command is complete. Example:
  4586. SET HOST www.columbia.edu http
  4587. IF FAIL EXIT 1 Can't contact server
  4588. HTTP GET kermit/index.html
  4589. At this point the connection is closed, since that's how HTTP 1.0
  4590. works. If you want to perform additional operations, you must establish
  4591. a new connection with another SET HOST command.
  4592. The HTTP command acts as a client to the Web server, except instead of
  4593. displaying the results like a Web browser would, it stores them. Any
  4594. HTTP command can (but need not) include any or all of the following
  4595. switches:
  4596. /AGENT:user-agent
  4597. Identifies the client to the server; "C-Kermit" or "Kermit-95"
  4598. by default.
  4599. /HEADER:header-line
  4600. Used for specifying any optional headers. A list of headers is
  4601. provided using braces for grouping:
  4602. /HEADER:{{tag:value}{tag:value}...}
  4603. For a listing of valid tag value and value formats seeRFC
  4604. 1945: Hypertext Transfer Protocol -- HTTP/1.0. A maximum of
  4605. eight headers may be specified.
  4606. /USER:name
  4607. In case a page requires a username for access.
  4608. /PASSWORD:password
  4609. In case a page requires a password for access.
  4610. /ARRAY:arrayname
  4611. Tells Kermit to store the response headers in the given array,
  4612. one line per element. The array need not be declared in advance.
  4613. Example:
  4614. C-Kermit? http /array:c get kermit/index.html
  4615. C-Kermit? show array c
  4616. Dimension = 9
  4617. 1. Date: Fri, 26 Nov 1999 23:12:22 GMT
  4618. 2. Server: Apache/1.3.4 (Unix)
  4619. 3. Last-Modified: Mon, 06 Sep 1999 22:35:58 GMT
  4620. 4. ETag: "bc049-f72-37d441ce"
  4621. 5. Accept-Ranges: bytes
  4622. 6. Content-Length: 3954
  4623. 7. Connection: close
  4624. 8. Content-Type: text/html
  4625. As you can see, the header lines are like MIME e-mail header lines:
  4626. identifier, colon, value. The /ARRAY switch is the only method
  4627. available to a script to process the server responses for a POST or PUT
  4628. command.
  4629. The HTTP commands are:
  4630. HTTP [ switches ] GET remote-filename [ local-filename ]
  4631. Retrieves the named file. If a local-filename is given, the file
  4632. is stored locally under that name; otherwise it is stored with
  4633. its own name.
  4634. HTTP [ switches ] HEAD remote-filename local-filename
  4635. Like GET except without actually getting the file; instead it
  4636. gets only the headers, storing them into the given file, whose
  4637. name must be given, one line per header item, as shown above in
  4638. the /ARRAY: switch description.
  4639. HTTP [ switches ] INDEX remote-directory [ local-filename ]
  4640. Retrieves the file listing for the given server directory. NOTE:
  4641. This command is not supported by most Web servers.
  4642. HTTP [ switches ] POST [ /MIME-TYPE:type ] local-file remote-file
  4643. Used to send a response as if it were sent from a form. The data
  4644. to be posted must be read from a file.
  4645. HTTP [ switches ] PUT [ /MIME-TYPE:type ] local-file remote-file
  4646. Uploads a local file to a server file.
  4647. HTTP [ switches ] DELETE remote-filename
  4648. Instructs the server to delete the specified filename.
  4649. 3. TERMINAL CONNECTION
  4650. 3.1. CONNECT Command Switches
  4651. The following switches (see Section 1.5) were added to the CONNECT
  4652. command in 7.0:
  4653. /QUIETLY
  4654. Don't print the "Connecting to..." or "Back at..." messages. CQ
  4655. is an invisible command synonym for CONNECT /QUIETLY.
  4656. /TRIGGER:string
  4657. Specify a trigger or triggers ( Section 3.2) effective for
  4658. this CONNECT command only, temporarily overriding any current
  4659. SET TERMINAL TRIGGER values ( Section 3.2).
  4660. Note: Other switches might also be available; type "connect ?" for a
  4661. list, "help connect" for a description of each.
  4662. 3.2. Triggers
  4663. Triggers were added for UNIX, VMS, AOS/VS, and K95 in C-Kermit 7.0.
  4664. SET TERMINAL TRIGGER string
  4665. Tells C-Kermit to look for the given string during all
  4666. subsequent CONNECT sessions, and if seen, to return to command
  4667. mode automatically, as if you had escaped back manually. If the
  4668. string includes any spaces, you must enclose it in braces.
  4669. Example:
  4670. set terminal trigger {NO CARRIER}
  4671. Comparisons are made after character-set translation.
  4672. If a string is to include a literal brace character, precede it with a
  4673. backslash:
  4674. ; My modem always makes this noise when the connection is lost:
  4675. set terminal trigger |||ppp\{\{\{\{UUUUUUU
  4676. If you want Kermit to look for more than one string simultaneously, use
  4677. the following syntax:
  4678. set terminal trigger {{string1}{string2}...{stringn}}
  4679. In this case, C-Kermit will return to command mode automatically if any
  4680. of the given strings is encountered. Up to 8 strings may be specified.
  4681. If the most recent return to command mode was caused by a trigger, the
  4682. new variable, \v(trigger), shows the trigger value; otherwise
  4683. \v(trigger) is empty.
  4684. The SHOW TRIGGER command displays the SET TERMINAL TRIGGER values as
  4685. well as the \v(trigger) value.
  4686. 3.3. Transparent Printing
  4687. As noted in the manual, C-Kermit's CONNECT command on UNIX is not a
  4688. terminal emulator, but rather a "semitransparent pipe" between the
  4689. terminal or emulator you are using to access C-Kermit, and the remote
  4690. host to which C-Kermit is connected. The "semitransparent" qualifier is
  4691. because of character-set translation as well as several actions taken
  4692. by the emulator in response to the characters or strings that pass
  4693. through it, such as APCs, Kermit packets (autodownload), triggers, etc.
  4694. The UNIX version of C-Kermit 7.0 adds another such action: Transparent
  4695. printing, also called Controller printing (as distinct from Autoprint
  4696. or line or screen print). It is intended mainly for use on UNIX
  4697. workstation consoles (as opposed to remote logins), but with some care
  4698. can also be used when accessing C-Kermit remotely.
  4699. Transparent printing is related to APC by sharing C-Kermit's built-in
  4700. ANSI escape-sequence parser to detect "printer on" and "printer off"
  4701. sequences from the host. When the printer-on sequence is received, all
  4702. subsequent arriving characters -- including NUL, control characters,
  4703. and escape sequences -- are sent to the SET PRINTER device instead of
  4704. to your screen until the printer-off sequence is received, or you
  4705. escape back, whichever happens first. These bytes are not translated or
  4706. modified or filtered in any way by Kermit (except for possibly
  4707. stripping of the 8th bit, as noted below), but if filtering or
  4708. translation is desired, this can be accomplished by your SET PRINTER
  4709. selection (e.g. by choosing a pipeline of filters).
  4710. By default, your SET PRINTER device is your default UNIX printer, but
  4711. it can also be a file, a command, or the null device (which causes all
  4712. printer material to be discarded). SeeUsing C-Kermit, 2nd Ed.,
  4713. p.41 for details.
  4714. Transparent printing is controlled by the command:
  4715. SET TERMINAL PRINT { ON, OFF }
  4716. When ON, transparent-print sequences are obeyed, and printing
  4717. occurs on the system where C-Kermit is running. When OFF,
  4718. transparent print sequences are ignored and passed through to
  4719. your actual terminal or emulator, along with the data they
  4720. enclose. OFF is the default, for compatibility with earlier
  4721. C-Kermit releases. As noted in the manual, when the current SET
  4722. PRINTER device is a file, transparent-print material is appended
  4723. to it; the file is not overwritten.
  4724. SET TERMINAL BYTESIZE { 7, 8 }
  4725. SET PARITY { EVEN, ODD, MARK, SPACE, NONE }
  4726. If the terminal bytesize is 7, or PARITY is not NONE, the 8th
  4727. bit of each byte is stripped prior to printing.
  4728. The transparent-print escape sequences are:
  4729. <ESC>[5i
  4730. Printer On. Send all subsequent incoming bytes to the printer
  4731. without any kind of filtering, translation, or alteration. Note:
  4732. <ESC> stands for ASCII character number 27 (decimal), Escape.
  4733. <ESC>[4i
  4734. Printer Off. Resume displaying incoming bytes on the screen.
  4735. These are the same sequences used by DEC VT100 and higher terminals and
  4736. other ANSI X3.64 and ISO 6429 compatible terminals. There is no
  4737. provision for selecting other printer-control sequences.
  4738. Restrictions:
  4739. 1. You must SET TERM TRANSPARENT-PRINT ON before you can use this
  4740. feature.
  4741. 2. Only the 7-bit forms of the escape sequences are supported. The
  4742. 8-bit CSI C1 control is not recognized.
  4743. 3. Autoprint is not supported, since this requires a full-fledged
  4744. terminal emulator with direct access to the screen.
  4745. 4. The start-print and stop-print sequences pass through to the screen
  4746. (there is no way to avoid this without causing unacceptable delays
  4747. or deadlocks in CONNECT mode). Thus if your terminal or emulator
  4748. also supports transparent printing via these same sequences, an
  4749. empty file will be sent to its printer. Normally this has no
  4750. effect.
  4751. Point (4) is similar to the situation with autodownload and APC -- when
  4752. you have several Kermit clients in a chain, you should take care that
  4753. these features are enabled in only one of them.
  4754. Example 1:
  4755. set printer {|lpr -Plaser} ; Specify the printer (if not default).
  4756. set term print on ; Enable transparent printing.
  4757. set term byte 8 ; Enable 8-bit characters.
  4758. connect ; Enter CONNECT mode.
  4759. Example 2:
  4760. set printer /home/users/olga/printer.log ; Send printer material to a file.
  4761. Example 3:
  4762. set printer {| grep -v ^Received | lpr} ; Filter out some lines
  4763. Then use "pcprint" or "vtprint" commands on the host to initiate
  4764. transparent print operations. SeeUsing C-Kermit, 2nd Ed., p.406
  4765. for details.
  4766. Here is a sample "pcprint" shell script for UNIX:
  4767. #!/bin/sh
  4768. echo -n '<ESC>[5i'
  4769. if [ $# -eq 0 ]; then
  4770. cat
  4771. else
  4772. cat $*
  4773. fi
  4774. echo -n '<FF><ESC>[4i'
  4775. # (end)
  4776. (Replace "<ESC>" by the actual ASCII Escape character and "<FF>" by the
  4777. ASCII Formfeed character).
  4778. If you always want transparent printing enabled, put "set term print
  4779. on" in your C-Kermit customization file (~/.mykermrc in UNIX). The "set
  4780. term bytesize" selection, however, is a property of each separate
  4781. connection.
  4782. 3.4. Binary and Text Session Logs
  4783. C-Kermit 7.0 corrects an oversight in earlier releases, in which binary
  4784. session logs (SET SESSION-LOG BINARY) translated character sets and
  4785. performed various formatting transformations (e.g. "newline mode")
  4786. before writing characters to the session log. In C-Kermit 7.0,
  4787. binary-mode session logging writes characters as they come in, before
  4788. anything (other that parity-bit stripping) is done to them. Text-mode
  4789. session logging records the characters after processing.
  4790. 4. FILE TRANSFER
  4791. Every file is transferred either in text mode (which implies
  4792. record-format and character-set translation) or binary mode (in which
  4793. each byte is sent literally without any kind of conversion). The mode
  4794. in which a file is transferred is controlled by (a) the default mode,
  4795. in the absence of any other indications; (b) the SET FILE TYPE command;
  4796. (c) various automatic mechanisms based on client/server negotiations,
  4797. directory information or filename patterns, etc.
  4798. The default FILE TYPE was changed from TEXT to BINARY in C-Kermit 7.0
  4799. because:
  4800. * Transferring a text file in binary mode does less damage than
  4801. transferring a binary file in text mode.
  4802. * Only binary-mode transfers can be recovered from the point of
  4803. failure.
  4804. * The automatic transfer-mode mechanisms switch to text mode on a
  4805. per-file basis anyway, so only those files that are not covered by
  4806. the automatic mechanisms are affected.
  4807. * All file transfers on the Web are done in binary mode, so people
  4808. are accustomed to it and expect it.
  4809. 4.0. BUG FIXES, MINOR CHANGES, AND CLARIFICATIONS
  4810. 4.0.0. Filenames with Spaces
  4811. Filenames that contain spaces are a major nuisance to a program like
  4812. Kermit, whose command language is line- and word-oriented, in which
  4813. words are separated by spaces and a filename is assumed to be a "word".
  4814. In general (unless noted otherwise in the description of a particular
  4815. command), there is only one way to refer to such files in Kermit
  4816. commands, and that is to enclose the name in braces:
  4817. send {this file}
  4818. Tells Kermit to send the file whose name is "this file" (two words, no
  4819. quotes). Of course, various circumlocutions are also possible, such as:
  4820. define \%a this file
  4821. send \%a
  4822. BUT, perhaps contrary to expectation, you can't use "\32" to represent
  4823. the space:
  4824. send this\32file
  4825. does not work. Why? Because the Kermit parser, which must work on many
  4826. operating systems including Windows, has no way of knowing what you
  4827. mean by "this\32file". Do you mean a file whose name is "this file" in
  4828. the current directory? Or do you mean a file whose name is "32file" in
  4829. the "this" subdirectory of the current directory? Guessing won't do
  4830. here; Kermit must behave consistently and deterministically in all
  4831. cases on all platforms.
  4832. Note that you can't use Esc or Tab within {...} for filename
  4833. completion, or question mark to get a filename list. However, you can
  4834. include wildcards; for example:
  4835. send {* *}
  4836. sends all files whose name contains a space.
  4837. All things considered, it is best to avoid spaces in file and directory
  4838. names if you can. Also see Section 5.4 on this topic.
  4839. 4.0.1. Packet out of Window
  4840. C-Kermit 6.0 could send packets "out of window" if the window size was
  4841. greater than 1 and ACKs had arrived out of order. Fixed in 6.1.
  4842. 4.0.2. MOVE after ADD SEND-LIST
  4843. ADD SEND-LIST followed by MOVE did not delete original files; fixed in
  4844. 6.1. Carrier loss was not detected during transfer; in 7.0 C-Kermit
  4845. checks for this (but results can not be guaranteed). In any case, the
  4846. protocol will eventually time out if the connection is lost.
  4847. 4.0.3. GET and RECEIVE As-Names
  4848. In 5A(190) through 6.0.192, the GET and RECEIVE as-name did not
  4849. properly override the RECEIVE PATHNAMES setting. In 7.0 it does.
  4850. 4.0.4. New Brief Statistics Listing
  4851. Version 7.0 adds a /BRIEF switch to the STATISTICS command, to display
  4852. a short file-transfer statistics report. /BRIEF is now the default. Use
  4853. /VERBOSE to see the full display, which is about 25 lines long.
  4854. 4.0.5. Improved FAST Command
  4855. The preinstalled definition of the FAST macro did not take enough
  4856. factors into account. Now it sets packet lengths and window sizes
  4857. appropriate to the configuration. Furthermore, in IRIX only, it might
  4858. restrict the SEND packet length to 4000, to work around a bug in the
  4859. IRIX Telnet server, depending on the IRIX version (seeckubwr.txt,
  4860. IRIX section). To see the built-in definition of the FAST macro, type
  4861. "show macro fast". To change it, simply define it to be whatever you
  4862. want -- it's just a macro, like any other.
  4863. 4.0.6. The SET SEND BACKUP Command
  4864. Version 7.0 adds SET SEND BACKUP { ON, OFF }. This tells whether backup
  4865. files should be sent. Backup files are the ones created by Kermit (and
  4866. EMACS, and possibly other applications) to preserve old copies of files
  4867. when creating new ones with the same name. Kermit does this when
  4868. receiving a file and its FILE COLLISION setting is BACKUP (or RENAME,
  4869. in which case it the new file gets the backup name). On most platforms,
  4870. the backup name is formed by adding:
  4871. .~n~
  4872. to the end of the filename, where "n" is a number. For example, if the
  4873. original file is oofa.txt, a backup file might be called:
  4874. oofa.txt.~1~
  4875. (or oofa.txt.~2~, etc). If you SET SEND BACKUP OFF, this tells Kermit
  4876. not to send files that have backup names. Normally, SET SEND BACKUP is
  4877. ON (as shown by SHOW PROTOCOL), and backup files are sent if their
  4878. names match the SEND file specification.
  4879. Also see PURGE, SET FILE COLLISION, SEND /NOBACKUP, DIRECTORY
  4880. /[NO]BACKUP.
  4881. 4.0.7. The SET { SEND, RECEIVE } VERSION-NUMBERS Command
  4882. VMS Only. Normally when sending files, VMS C-Kermit strips the version
  4883. number. For example, if the file is FOO.BAR;34, the name is sent as
  4884. FOO.BAR (without the ";34"). If you want to keep version numbers on
  4885. when sending files, use SET SEND VERSION-NUMBERS ON. The effect depends
  4886. on the receiver.
  4887. Normally when receiving files, and an incoming filename includes a
  4888. VMS-style version number (such as FOO.BAR;34) VMS C-Kermit strips it
  4889. before trying to create the new file; this way the new file receives
  4890. the next highest version number in the customary manner for VMS. If you
  4891. want version numbers on incoming filenames to be used in creating the
  4892. new files, use SET RECEIVE VERSION-NUMBERS ON.
  4893. Normally these commands would be effective only when VMS C-Kermit is
  4894. exchanging files with a non-VMS Kermit program, since VMS-to-VMS
  4895. transfers use labeled mode unless you have gone out of your way to
  4896. defeat it.
  4897. Example: You want to send all versions of all files in the current
  4898. directory from a VMS C-Kermit client to a UNIX C-Kermit server. Use:
  4899. set send version-numbers on
  4900. send *.*;*
  4901. The resulting Unix files will have VMS-style version numbers as part of
  4902. their name, for example "foo.bar;1", "foo.bar;2", etc.
  4903. Now suppose you want to send these files from Unix to another VMS
  4904. system and preserve the version numbers. Again we have a Unix C-Kermit
  4905. server and VMS C-Kermit client. Give these commands to the client:
  4906. set receive version-numbers on
  4907. get *
  4908. 4.0.8. The SET { SEND, RECEIVE } { MOVE-TO, RENAME-TO } Commands
  4909. These commands are persistent global versions of the /MOVE-TO: and
  4910. /RENAME-TO: switches of the SEND, GET, and RECEIVE commands. They
  4911. should normally be used only when setting up a dedicated
  4912. transaction-processing application, in which each file is to be moved
  4913. or renamed immediately after, and only if, it is transferred
  4914. successfully, so that (for example) an independent, concurrent process
  4915. can notice when new files appear and process them immediately without
  4916. having to guess whether they are complete.
  4917. 4.0.9. SET FILE INCOMPLETE AUTO
  4918. SET FILE INCOMPLETE { KEEP, DISCARD }, which tells whether to keep or
  4919. discard incompletely received files, has a new option, AUTO, which is
  4920. also the default. It means KEEP the incomplete file if the transfer is
  4921. in binary mode, otherwise DISCARD it. This reduces the chances that a
  4922. subsequent recovery operation (RESEND, REGET, etc) could produce a
  4923. corrupt file, since recovery works only for binary-mode transfers.
  4924. 4.1. FILE-TRANSFER FILENAME TEMPLATES
  4925. File-transfer filename templates allow files to be renamed
  4926. automatically by the file sender, the receiver, or both, during
  4927. transfer of groups of files.
  4928. 4.1.1. Templates in the As-Name
  4929. Prior to C-Kermit 6.1 and Kermit 95 1.1.12 the only options that could
  4930. be used to affect the names of files being transferred were SET
  4931. FILENAMES { LITERAL, CONVERTED } and SET { SEND, RECEIVE } PATHNAMES {
  4932. ON, OFF }, plus the "as-name" feature of the SEND (MOVE, etc) and
  4933. RECEIVE commands.
  4934. Previously, the as-name could be used only for a single file. For
  4935. example:
  4936. SEND FOO BAR
  4937. would send the file FOO under the name BAR, but:
  4938. SEND *.TXT anything
  4939. was not allowed, since it would give the same name to each file that
  4940. was sent. When receiving:
  4941. RECEIVE FOO
  4942. would rename the first incoming file to FOO before storing it on the
  4943. disk, but subsequent files would not be renamed to FOO, since this
  4944. would result in overwriting the same file repeatedly. Instead, they
  4945. were stored under the names they arrived with.
  4946. Beginning in C-Kermit 6.1 and Kermit 95 1.1.12, it is possible to
  4947. specify as-names in SEND, RECEIVE, and related commands even for file
  4948. groups. This is accomplished by using replacement variables in the
  4949. as-name, along with optional material such character-string functions
  4950. and/or constant strings. An as-name containing replacement variables is
  4951. called a filename template.
  4952. The key to filename templates is the new variable:
  4953. \v(filename)
  4954. During file transfer it is replaced by the name of each file currently
  4955. being transferred (after transfer, it is the name of the last file
  4956. transferred).
  4957. So, for example:
  4958. send *.txt \v(filename).new
  4959. sends each file with its own name, but with ".new" appended to it. Of
  4960. course if the name already contains periods, this could confuse the
  4961. file receiver, so you can also achieve fancier effects with
  4962. constructions like:
  4963. send *.txt \freplace(\v(filename),.,_).new
  4964. which replaces all periods in the original filename by underscores, and
  4965. then appends ".new" to the result. So, for example, oofa.txt would be
  4966. sent as oofa_txt.new.
  4967. Another new variable that is useful in this regard is \v(filenumber),
  4968. which is the ordinal number of the current file in the file group, so
  4969. you can also:
  4970. send *.txt FILE\flpad(\v(filenum),2,0)
  4971. resulting in a series of files called FILE00, FILE01, FILE02, etc. (At
  4972. the end of the transfer, \v(filenum) tells the number of files that
  4973. were transferred).
  4974. If you specify a constant as-name when sending a file group:
  4975. send *.txt thisnameonly
  4976. Kermit complains and asks you to include replacement variables in the
  4977. as-name. You should generally use \v(filename) or \v(filenumber) for
  4978. this purpose, since other variables (with the possible exception of
  4979. date/time related variables) do not change from one file to the next.
  4980. But Kermit accepts any as-name at all that contains any kind of
  4981. variables for file group, even if the variable will not change. So:
  4982. send *.txt \%a
  4983. is accepted, but all files are sent with the same name (the value of
  4984. \%a, if it has one and it is constant). If the variable has no value at
  4985. all, the files are sent under their own names.
  4986. Of course, the value of \%a in the previous example need not be
  4987. constant:
  4988. define \%a FILE\flpad(\v(filenum),2,0)_at_\v(time)
  4989. send *.txt \%a
  4990. The RECEIVE command, when given without an as-name, behaves as always,
  4991. storing all incoming files under the names they arrive with, subject to
  4992. SET FILE NAME and SET RECEIVE PATHNAMES modifications (Section
  4993. 4.10).
  4994. However, when an as-name is given in the RECEIVE command, it is applied
  4995. to all incoming files rather than to just the first. If it does not
  4996. contain replacement variables, then the current FILE COLLISION setting
  4997. governs the result. For example:
  4998. receive foo
  4999. will result in incoming files named foo, foo.~1~, foo.~2~, and so on,
  5000. with the default FILE COLLISION setting of BACKUP. If it does contain
  5001. replacement variables, of course they are used.
  5002. When receiving files, the \v(filename) variable refers to the name that
  5003. was received in the incoming file-header packet, BEFORE any processing
  5004. by SET FILE NAMES or SET RECEIVE PATHNAMES. Since the filenames in
  5005. file-header packets are usually in uppercase, you would need to convert
  5006. them explicitly if you want them in lowercase, e.g.:
  5007. receive \flower(\v(filename)).new
  5008. 4.1.2. Templates on the Command Line
  5009. On the command-line, use templates as shown above as the -a option
  5010. argument, bearing in mind the propensity of UNIX and perhaps other
  5011. shells to treat backslash as a shell escape character. So in UNIX (for
  5012. example):
  5013. kermit -s oofa.* -a x.\\v(filenum)
  5014. By the way, this represents a change from 6.0 and earlier releases in
  5015. which the as-name (-a argument or otherwise) was not evaluated by the
  5016. command parser. Thus, for example, in VMS (where the shell does not
  5017. care about backslashes), it was possible to:
  5018. kermit -s oofa.txt -a c:\tmp\oofa.txt
  5019. Now backslashes in the as-name must be quoted not only for the shell
  5020. (if necessary) but also for Kermit itself:
  5021. kermit -s oofa.txt -a c:\\tmp\\oofa.txt ; Kermit only
  5022. kermit -s oofa.txt -a c:\\\\tmp\\\\oofa.txt ; Shell and Kermit
  5023. You can also use the \fliteral() function for this:
  5024. kermit -s oofa.txt -a \fliteral(c:\tmp\oofa.txt) ; Kermit only
  5025. kermit -s oofa.txt -a \\fliteral(c:\\tmp\\oofa.txt) ; Shell and Kermit
  5026. 4.1.3. Post-Transfer Renaming
  5027. Filename templates are now also useful in SET { SEND, RECEIVE }
  5028. RENAME-TO and in the /RENAME-TO: switch, that can be given to the SEND,
  5029. GET, or RECEIVE commands; this is similar to an as-name, but is
  5030. effective on a per-file basis if and only if the file was transferred
  5031. successfully.
  5032. MOVE-TO and RENAME-TO address a requirement commonly stated for
  5033. transaction processing and similar systems. Suppose, for example, a
  5034. central system "X" accepts connections from multiple clients
  5035. simultaneously; a process on X waits for a file to appear and then
  5036. processes the file. This process must have a way of knowing when the
  5037. file has been completely and successfully transferred before it starts
  5038. to process it. This can be accomplished easily using C-Kermit's SET {
  5039. SEND, RECEIVE } { MOVE-TO, RENAME-TO } command or /MOVE-TO: or
  5040. /RENAME-TO: switches, described inSections 4.7.1 through
  5041. 4.7.3.
  5042. Here's an example for the client side, in which files to be sent are
  5043. placed in a certain directory (/usr/olga/tosend in this example) by
  5044. another process when they are ready to go. This might be in a hospital
  5045. or big doctor's office, where medical insurance claims are entered at a
  5046. number of workstations, and then deposited in the "tosend" directory,
  5047. from which they are sent to a claims clearinghouse. We assume the
  5048. connection is already made and a Kermit server is on the other end.
  5049. local srcdir findir ; Declare local (automatic) variables
  5050. assign srcdir /usr/olga/tosend ; Local source directory (files to send)
  5051. assign findir /usr/olga/sent ; Where to move files after they are sent
  5052. log transactions ; Keep a log of transfers
  5053. cd \m(srcdir) ; Change to the source directory
  5054. while true { ; Loop forever...
  5055. send /move-to:\m(findir) * ; Send all files
  5056. sleep 60 ; Sleep a minute
  5057. } ; Go back and do it again
  5058. Note how simple this is. Once each file is sent, it is moved so it
  5059. won't be sent again (you could also use SEND /RENAME-TO: or even SEND
  5060. /DELETE). If a transfer fails, the file is not moved and so we try
  5061. again to send it next time around. If there are no files to send, the
  5062. SEND command does nothing but a message is printed; you can avoid the
  5063. message by checking first to see if any files are in the directory:
  5064. while true { ; Loop forever...
  5065. if > \ffiles(*) 0 - ; If there are any files
  5066. send /move-to:\m(findir) * ; send them.
  5067. sleep 60 ; Sleep a minute.
  5068. } ; Go back and do it again.
  5069. It's even simpler on the server side (here again we assume the
  5070. connection is already in place):
  5071. local rcvdir findir ; Declare local (automatic) variables
  5072. assign rcvdir /usr/ivan/tmp ; Temporary receiving directory
  5073. assign findir /usr/ivan/new ; Where to move files after reception
  5074. log transactions ; Keep a log of transfers
  5075. cd \m(rcvdir) ; Change to the source directory
  5076. set receive move-to \m(findir) ; Declare move-to directory.
  5077. server ; Enter server mode.
  5078. A separate process (e.g. the medical claim-form decoder) can look for
  5079. files appearing in the /usr/ivan/new directory and process them with
  5080. every confidence that they have been completely received.
  5081. Note that the use of MOVE-TO can result in moved files overwriting one
  5082. another (the application would normally avoid this by assigning each
  5083. transaction a unique, e.g. based on customer number and claim number).
  5084. But if filename collisions are a possibility in your application,
  5085. RENAME-TO might be a better choice; you can use any variables you like
  5086. in the template to ensure uniqueness of the RENAME-TO filename; for
  5087. example:
  5088. SET RECEIVE RENAME-TO \v(filename)_\v(ndate)_\v(ntime)_\v(userid)_\v(pid)
  5089. 4.2. FILE-TRANSFER PIPES AND FILTERS
  5090. 4.2.1. INTRODUCTION
  5091. Beginning in C-Kermit 6.1 and Kermit 95 1.1.12, it is possible to send
  5092. from a command, or "pipe", as well as from a file, and to receive to a
  5093. pipe or command. In a typical example, we might want to transfer an
  5094. entire directory tree from one UNIX system to another (but without
  5095. using the methods described inSections 4.3 ,4.10,
  5096. 4.11, and4.15). We could do this in multiple steps as
  5097. follows:
  5098. 1. Create a tar archive of the desired directory tree
  5099. 2. Compress the tar archive
  5100. 3. Transfer it in binary mode to the other computer
  5101. 4. Decompress it
  5102. 5. Extract the directory tree from the tar archive
  5103. But this is inconvenient and it requires a temporary file, which might
  5104. be larger than we have room for.
  5105. The new pipe-transfer feature lets you do such things in a single step,
  5106. and without intermediate files.
  5107. Additional new features, also discussed here, let you specify pre- and
  5108. post- processing filters for outbound and incoming files, and give you
  5109. a way to insert the output from shell or system commands into C-Kermit
  5110. commands.
  5111. The file-transfer related features are available only with Kermit
  5112. protocol, not with any external protocols, nor with K95's built-in
  5113. XYZMODEM protocols (because XYZMODEM recovers from transmission errors
  5114. by rewinding the source file, and you can't rewind a pipe).
  5115. This section begins by discussing the simple and straightforward use of
  5116. these features in UNIX, in which pipes and input/output redirection are
  5117. a fundamental component and therefore "just work", and then goes on to
  5118. discuss their operation in Windows and OS/2, where matters are much
  5119. more complicated.
  5120. 4.2.1.1. TERMINOLOGY
  5121. Standard Input
  5122. This is a precise technical term denoting the normal source of
  5123. input for a command or program, which is the keyboard of your
  5124. terminal by default, but which can be redirected to a file or
  5125. pipe.
  5126. Stdin
  5127. Abbreviation for Standard Input.
  5128. Standard Output
  5129. A precise technical term denoting the normal destination for
  5130. output from a command or program, which is your terminal screen
  5131. by default, but which can be redirected to a file.
  5132. Stdout
  5133. Abbreviation for Standard Output.
  5134. Stdio
  5135. Abbreviation for Standard Input / Standard Output.
  5136. I/O
  5137. Abbreviation for Input / Output.
  5138. Shell
  5139. Text-based system command processor, such as the UNIX shell, DOS
  5140. COMMAND.COM, etc.
  5141. Pipe
  5142. A mechanism by which the standard output of one program is sent
  5143. to the standard input of another.
  5144. Pipeline
  5145. A series of programs connected by pipes.
  5146. 4.2.1.2. NOTATION
  5147. In command descriptions, "command" is replaced by a shell or system
  5148. command or pipeline. The command names specified in these commands are
  5149. interpreted by your shell, just as if you were typing them at the shell
  5150. prompt, and so if they are in your PATH, they will be found in the
  5151. expected manner. Therefore you don't have to specify complete pathnames
  5152. for commands that are programs (but it shouldn't hurt if you do).
  5153. The normal notation for I/O redirection is as follows:
  5154. < Read Stdin from the given file.
  5155. > Send Stdout to the given file.
  5156. | Send Stdout from the command on the left to the command on the right.
  5157. Examples:
  5158. sort < foo > bar
  5159. Sorts the lines in file "foo" and writes the results to file
  5160. "bar"
  5161. grep -c "some text" *.txt | grep -v ":0" | sort | pr -3 | lpr
  5162. This is a command pipeline composed of 5 commands:
  5163. grep -c "some text" *.txt
  5164. Looks in all files whose names end with ".txt" for the string
  5165. "some text" and writes to Stdout the names of each file followed
  5166. by a colon and the number of occurrences in each.
  5167. grep -v ":0"
  5168. Prints to Stdout the lines from Stdin that do NOT contain the
  5169. string ":0", in this case, it removes the names of files that do
  5170. not contain "some text".
  5171. sort
  5172. Sorts the lines from Stdin alphabetically to Stdout.
  5173. pr -3
  5174. Arranges the lines from Stdin in three columns.
  5175. lpr
  5176. Prints its Stdin on the default printer.
  5177. Note that the Kermit features described here work only with commands
  5178. that use Stdio. If you attempt to use them with commands whose input
  5179. and output can not be redirected, Kermit will most likely get stuck.
  5180. Kermit has no way of telling how an external command works, nor what
  5181. the syntax of the shell is, so it's up to you to make sure you use
  5182. these features only with redirectable commands.
  5183. The quoting rules of your shell apply to the command. Thus in UNIX,
  5184. where C-Kermit tries to use your preferred shell for running commands,
  5185. shell "metacharacters" within commands must be escaped if they are to
  5186. be taken literally, using the methods normal for your shell. For
  5187. example, the UNIX tr (translate) command must have its arguments in
  5188. quotes:
  5189. tr "[a-z]" "[A-Z]"
  5190. otherwise the shell is likely to replace them by all filenames that
  5191. match, which is probably not what you want. This is also true when
  5192. using your shell directly, and has nothing to do with Kermit.
  5193. 4.2.1.3. SECURITY
  5194. Some sites might not wish to allow access to system commands or
  5195. external programs from within Kermit. Such access, including all the
  5196. features described here, can be disabled in various ways:
  5197. 1. When building from source code, include -DNOPUSH among the CFLAGS.
  5198. 2. At runtime, give the NOPUSH command.
  5199. 3. For server mode, give the DISABLE HOST command.
  5200. 4. Implicit use of pipes can be disabled as described inSection
  5201. 4.2.4.
  5202. Note: 3 and 4 are not necessary if you have done 1 or 2.
  5203. 4.2.2. Commands for Transferring from and to Pipes
  5204. SEND /COMMAND sends data from a command or command pipeline, and
  5205. RECEIVE /COMMENT writes data to a command or pipeline. The GET /COMMAND
  5206. command asks a server to send material, and then writes the incoming
  5207. material to a command or pipeline. These features, along with switches
  5208. (like "/COMMAND", described in Section 4.7) are new to C-Kermit
  5209. 6.1. The following synonyms are also provided:
  5210. CSEND = SEND /COMMAND
  5211. CRECEIVE = RECEIVE /COMMAND
  5212. CGET = GET /COMMAND
  5213. None of these commands can be used if a SEND or RECEIVE FILTER
  5214. (respectively, Section 4.2.3) is in effect, or if a NOPUSH command
  5215. ( Section 4.2.1.3) has been given, or if the current protocol is
  5216. not Kermit.
  5217. 4.2.2.1. Sending from a Command
  5218. SEND /COMMAND command [ as-name ]
  5219. SEND /AS-NAME:as-name /COMMAND command
  5220. CSEND command [ as-name ]
  5221. These three forms are the same. They work like the SEND command,
  5222. but instead of sending a file, it sends the standard output of
  5223. the given command, either under the command's own name, or else
  5224. with the given as-name. If the command contains spaces, it must
  5225. be enclosed in braces. Braces should also be used for the
  5226. as-name if it contains spaces. If braces are included around
  5227. either the command or the as-name, they are removed after
  5228. parsing but before use. As with SEND, the transfer is in text or
  5229. binary mode according the current FILE TYPE setting, unless you
  5230. override the global transfer mode by including a /TEXT or
  5231. /BINARY switch. The command must require no input.
  5232. When sending from a command or pipeline, C-Kermit has no way of knowing
  5233. in advance how much data will be sent, and so it can not send the size
  5234. to the other Kermit in the Attribute packet, and so the receiving
  5235. Kermit has no way of displaying "percent done" or a progress bar
  5236. (thermometer).
  5237. Examples that make sense in text mode (illustrated by common UNIX
  5238. commands):
  5239. SEND /COMMAND finger
  5240. CSEND finger
  5241. sends the current "finger" listing (who's logged in) under the
  5242. name "finger". The two forms "send /command" and "csend" are
  5243. equivalent; we won't bother showing them both in the rest of the
  5244. examples.
  5245. SEND /COMMAND:{finger}
  5246. CSEND {finger}
  5247. Same as previous example (braces are removed from "{finger}").
  5248. SEND /COMMAND:{ finger }
  5249. CSEND { finger }
  5250. Same as previous example, but note that the spaces are kept.
  5251. This does not prevent the shell from running the "finger"
  5252. program, but its output is sent under the name " finger " (with
  5253. a leading and trailing space).
  5254. SEND /COMMAND:finger /AS-NAME:userlist
  5255. CSEND finger userlist
  5256. sends the current finger listing under the name "userlist".
  5257. SEND /COMMAND:{finger | sort -r} /AS-NAME:userlist
  5258. CSEND {finger | sort -r} userlist
  5259. sends the current finger listing, sorted in reverse order, under
  5260. the name "userlist". The braces are needed to distinguish the
  5261. command from the as-name.
  5262. SEND /COMMAND:{finger | sort -r} /AS-NAME:{userlist}
  5263. CSEND {finger | sort -r} {userlist}
  5264. Same as previous example (braces are removed from "{userlist}").
  5265. SEND /COMMAND:{finger | sort -r}
  5266. /AS-NAME:{\freplace(\v(filename),\32,_)}
  5267. CSEND {finger | sort -r} {\freplace(\v(filename),\32,_)}
  5268. Like the previous example, but sends the output of the command
  5269. under the name of the command, but with all spaces (\32)
  5270. replaced by underscores, so the as-name is "finger_|_sort_-r".
  5271. Examples that make sense in binary mode (three equivalent forms are
  5272. shown):
  5273. SEND /COMMAND /BINARY {tar cf - . | gzip -c} mydir.tar.gz
  5274. SEND /COMMAND /BINARY /AS-NAME:mydir.tar.gz {tar cf - . | gzip -c}
  5275. CSEND /BINARY {tar cf - . | gzip -c} mydir.tar.gz
  5276. Makes a tar archive of the current directory, compresses it with
  5277. the GNU gzip program, and sends it as "mydir.tar.gz". The other
  5278. Kermit can, of course, just store it as a file, or it can use
  5279. CRECEIVE to uncompress and dearchive it as part of the transfer
  5280. process.
  5281. When using a "pipeline" of commands in the command field, obviously,
  5282. the first command must not require any input, and the last command
  5283. should produce some output, and all intermediate commands should get
  5284. some input and produce some output.
  5285. 4.2.2.2. Receiving to a Command
  5286. RECEIVE /COMMAND command
  5287. CRECEIVE command
  5288. This is like RECEIVE, except incoming material is written to the
  5289. standard input of the given command, in text or binary mode
  5290. according to the normal rules for file reception. Be sure to
  5291. include a redirector to a file (if the command normally writes
  5292. to standard output), or the output of the command won't go
  5293. anywhere. The command may contain spaces; braces are not needed,
  5294. but they are removed if used.
  5295. WARNING: C-Kermit has no way of knowing anything about the command, or
  5296. even whether it is a command. Thus this command will always cause
  5297. C-Kermit to enter protocol mode, as long as some text is specified in
  5298. the command field. However, if the text does not correspond to a
  5299. command, the transfer will eventually fail with a message such as
  5300. "Error writing data" or "Failure to close file".
  5301. Examples for text mode (in UNIX):
  5302. RECEIVE /COMMAND sort -r > reverse.txt
  5303. CRECEIVE sort -r > reverse.txt
  5304. The text that is received is sorted in reverse order and stored
  5305. in the file "reverse.txt". The two forms shown are equivalent.
  5306. RECEIVE /COMMAND {sort -r > reverse.txt}
  5307. CRECEIVE {sort -r > reverse.txt}
  5308. The same as the previous example; if braces are included, they
  5309. are simply removed.
  5310. RECEIVE /COMMAND {sort -r > \flower(\v(filename)).reverse}
  5311. CRECEIVE {sort -r > \flower(\v(filename)).reverse}
  5312. Same but stores result under the incoming filename, lowercased,
  5313. and with ".reverse" appended to it.
  5314. RECEIVE /COMMAND sort
  5315. CRECEIVE sort
  5316. Does nothing useful, since the output of sort has nowhere to go.
  5317. RECEIVE /COMMAND sort -r | pr -3 | lpr -Plaserjet
  5318. CRECEIVE sort -r | pr -3 | lpr -Plaserjet
  5319. The text that is received is sorted in reverse order, arranged
  5320. into three columns, and sent to the "laserjet" printer.
  5321. Examples for binary mode:
  5322. RECEIVE /COMMAND:{gunzip -c | tar xf -}
  5323. CRECEIVE {gunzip -c | tar xf -}
  5324. Assuming the data that is received is a compressed tar archive,
  5325. uncompresses the archive and passes it to tar for extraction. In
  5326. this case the braces are needed because otherwise the final "-"
  5327. would be taken as a command continuation character (see
  5328. Using C-Kermit, 2nd Edition, p.33).
  5329. GET /COMMAND remote-file command
  5330. GET /COMMAND /AS-NAME:command remote-file
  5331. CGET remote-file command
  5332. This command tells the Kermit client to send a GET request for
  5333. the given remote file to a Kermit server. Unlike GET, however,
  5334. the incoming material is written to a command, rather than to a
  5335. file. If the remote-file or the command contain spaces, they
  5336. must be enclosed in braces. The same cautions about the command
  5337. apply as for CRECEIVE.
  5338. Examples (for UNIX):
  5339. GET /COMMAND oofa.txt sort -r > oofa.new
  5340. GET /COMMAND {oofa.txt} {sort -r > oofa.new}
  5341. CGET oofa.txt sort -r > oofa.new
  5342. CGET {oofa.txt} {sort -r > oofa.new}
  5343. These four are equivalent. Each of them requests the server to
  5344. send its "oofa.txt" file, and as it arrives, it is sorted in
  5345. reverse order and written to "oofa.new".
  5346. GET /COMMAND {profile exec a} lpr
  5347. GET /COMMAND {profile exec a} {lpr}
  5348. GET /COMMAND /AS-NAME:lpr {profile exec a}
  5349. GET /COMMAND /AS-NAME:{lpr} {profile exec a}
  5350. GET /COMMAND /AS:lpr {profile exec a}
  5351. CGET {profile exec a} lpr
  5352. CGET {profile exec a} {lpr}
  5353. Here the remote filename contains spaces so it MUST be enclosed
  5354. in braces. As it arrives it is sent to the lpr program for
  5355. printing. Braces are optional around "lpr" since it contains no
  5356. spaces.
  5357. GET /COMMAND *.txt {cat >> new.txt}
  5358. GET /AS-NAME:{cat >> new.txt} /COMMAND *.txt
  5359. CGET *.txt {cat >> new.txt}
  5360. This gets all the ".txt" files from the server and concatenates
  5361. them all into a single "new.txt" file on the client.
  5362. GET /COMMAND *.txt {echo \v(filename)>>new.txt;cat>>new.txt}
  5363. CGET *.txt {echo \v(filename)>>new.txt;cat>>new.txt}
  5364. As above, but inserts each file's name before its contents.
  5365. 4.2.3. Using File-Transfer Filters
  5366. The commands described in Section 4.2.2 let you send the output of
  5367. a command, or receive data into a command. But what if you want to
  5368. specify preprocessing for files that you send, or postprocessing of
  5369. files that you receive, even when multiple files are involved? For this
  5370. you need a way to specify send and receive filters. The commands are
  5371. SET SEND FILTER and SET RECEIVE FILTER; SHOW PROTOCOL displays the
  5372. current settings.
  5373. 4.2.3.1. The SEND Filter
  5374. SET SEND FILTER [ command ]
  5375. This command specifies a command to be run on any file that you
  5376. SEND (or MOVE, MSEND, etc). It also applies to files sent when
  5377. in server mode, in response to GET commands, but not to the
  5378. results of REMOTE commands like REMOTE DIRECTORY, REMOTE TYPE,
  5379. REMOTE HOST, etc. The command may be, but need not be, enclosed
  5380. in braces; if it is, the braces are stripped before use. The
  5381. output of this command is sent, rather than the file itself. The
  5382. current FILE TYPE setting (TEXT or BINARY) applies to the output
  5383. of the command. The command must contain at least one instance
  5384. of \v(filename), for which the name of the actual file is
  5385. substituted. If the command is omitted, the send filter is
  5386. removed and files are sent in the normal manner.
  5387. The SET SEND FILTER sets up a "global" filter -- that is, one that
  5388. applies to all subsequent file-sending commands until you change or
  5389. remove it. You can also specify a "local" filter to be used in a
  5390. specific file-sending command by using the /FILTER switch (see
  5391. Section 1.5); for example:
  5392. SEND /FILTER:command [ other-switches ] filename
  5393. Besides \v(filename), you can include any other script programming
  5394. notation in the send filter: variable names, array references, calls to
  5395. built-in string or other functions, and so on. These are evaluated
  5396. during file transfer, NOT during parsing, and they are evaluated
  5397. separately for each file.
  5398. When the SEND or MOVE (SEND /DELETE) command is used with a send
  5399. filter, the output from the filter is sent under the file's original
  5400. name unless you specify an "as-name" or template. The Attribute packet
  5401. (if any) contains the original file's attributes (size, creation date,
  5402. etc). So (for example) if the filter changes the file's size, the
  5403. progress thermometer might be wrong. (We can't send the size of the
  5404. output from the filter, because it is not known until the transfer is
  5405. finished.) If you prefer that the size not be sent, use "set attributes
  5406. size off".
  5407. You can not use send filters with RESEND (SEND /RECOVER) or PSEND (SEND
  5408. /START).
  5409. Examples for text mode:
  5410. SET SEND FILTER sort -r \v(filename) ; Braces may be omitted
  5411. SET SEND FILTER {sort -r \v(filename)} ; Braces may be included
  5412. SEND *.txt
  5413. This sends every file in the current directory whose name ends
  5414. with ".txt" under its own name, but with its lines sorted in
  5415. reverse order.
  5416. SEND /FILTER:{sort -r \v(filename)} *.txt
  5417. Same as above, but the filter applies only to this SEND command.
  5418. Braces are required in this case.
  5419. SET SEND FILTER {sort -r \v(filename)}
  5420. SEND oofa.txt reverse.txt
  5421. Sends the oofa.txt file with its lines sorted in reverse order
  5422. under the name "reverse.txt".
  5423. SET SEND FILTER {sort -r \v(filename)}
  5424. SEND oofa.* \v(filename).reverse
  5425. Sends all the oofa.* files with their lines sorted in reverse
  5426. order; each file is sent under its own name but with ".reverse"
  5427. appended to it.
  5428. SET SEND FILTER {tr "[a-z]" "[A-Z]" < \v(filename)}
  5429. SEND *.txt
  5430. Sends all ".txt" files under their own names, but uppercasing
  5431. their contents.
  5432. Note that the SEND FILTER applies not only to files that are sent with
  5433. SEND, MOVE, MSEND, etc, but also to files sent by the C-Kermit server
  5434. in response to GET requests.
  5435. Examples for binary mode:
  5436. SET SEND FILTER {gzip -c \v(filename)}
  5437. SEND /BINARY oofa.txt oofa.txt.gz
  5438. Sends the oofa.txt file, compressed by gzip, as oofa.txt.gz.
  5439. SEND /BINARY /FILTER:{gzip -c \v(filename)} oofa.txt oofa.txt.gz
  5440. As above, but the filter applies only to this SEND command.
  5441. SET SEND FILTER {gzip -c \v(filename)}
  5442. SEND /BINARY oofa.* \fupper(\replace(\v(filename),.,_)).GZ
  5443. Sends all the oofa.* files, compressed by gzip, each under its
  5444. own name, but with the name uppercased, all periods within the
  5445. name converted to underscores, and ".GZ" appended to it. So, for
  5446. example, "oofa.txt" is sent as "OOFA_TXT.GZ".
  5447. In the gzip examples, note that the amount of data that is sent is
  5448. normally less than the original file size because gzip compresses the
  5449. file. But Kermit sends the original file size ahead in the attribute
  5450. packet anyway (unless you tell it not too). Thus the transfer will
  5451. probably appear to terminate early, e.g. when the receiver's
  5452. file-transfer display thermometer is only at 40%. If this annoys you,
  5453. tell Kermit to "set attribute length off". On the other hand, you can
  5454. use the final position of the thermometer as a measure of the
  5455. effectiveness of compression.
  5456. 4.2.3.2. The RECEIVE Filter
  5457. SET RECEIVE FILTER [ command ]
  5458. This command specifies that the given command will be run on any
  5459. file that is received before it is written to disk. The command
  5460. may be, but need not be, enclosed in braces; if it is the braces
  5461. are stripped before use. The following two commands are
  5462. equivalent:
  5463. SET RECEIVE FILTER sort -r > \v(filename)
  5464. SET RECEIVE FILTER {sort -r > \v(filename)}
  5465. The RECEIVE filter command may contain a "\v(filename)" sequence to be
  5466. replaced by the incoming filename from the file header packet, but it
  5467. is not required. However you must use it whenever your filter would
  5468. normally write to Stdout, otherwise its output will be lost.
  5469. The RECEIVE filter command may contain one or more "\v(filename)"
  5470. sequence to be replaced by the incoming filename from the file header
  5471. packet, but it is not required. However you must use it whenever your
  5472. filter would normally write to Stdout, otherwise its output will be
  5473. lost.
  5474. RECEIVE /FILTER:command and GET /FILTER:command can also be used to
  5475. specify a filter to be used for only one file-transfer operation.
  5476. UNIX examples for text mode:
  5477. SET RECEIVE FILTER lpr
  5478. RECEIVE
  5479. All the files that are received are sent to the default UNIX
  5480. print spooler.
  5481. RECEIVE /FILTER:lpr
  5482. Same as above, except the lpr filter is used only with this
  5483. RECEIVE command.
  5484. RECEIVE lpr
  5485. This is probably not what you want; it creates a file called
  5486. lpr.
  5487. SET RECEIVE FILTER {sort -r > \v(filename)}
  5488. RECEIVE
  5489. Stores each incoming file with its lines sorted in reverse
  5490. order, under its own name.
  5491. RECEIVE /FILTER:{sort -r > \v(filename)}
  5492. As above, but the filter is used only for this RECEIVE command.
  5493. SET RECEIVE FILTER sort -r > \v(filename)
  5494. RECEIVE reverse.txt
  5495. Stores each incoming file with its lines sorted in reverse
  5496. order, under the name "reverse.txt". The actual result depends
  5497. on the FILE COLLISION setting. If it is OVERWRITE and multiple
  5498. files arrive, then each incoming file destroys the previous one.
  5499. If it is BACKUP (the default), filename conflicts are resolve by
  5500. adding "version numbers" to the filenames: reverse.txt,
  5501. reverse.txt.~1~, reverse.txt.~2~, etc.
  5502. SET RECEIVE FILTER sort -r > \v(filename)
  5503. RECEIVE \v(filename).reverse
  5504. Stores each incoming file with its lines sorted in reverse
  5505. order, under the name it arrived with, but with ".reverse"
  5506. appended to it.
  5507. SET RECEIVE FILTER sort -r > \v(filename)
  5508. RECEIVE \flower(\v(filename)).reverse
  5509. Like the previous example, but ensures that the filename is
  5510. lowercase.
  5511. Examples for binary mode:
  5512. SET RECEIVE FILTER gunzip -c > \v(filename)
  5513. RECEIVE
  5514. This receives one or more presumably compressed file and
  5515. uncompresses each one into a file having the same name it was
  5516. sent with. For example, if the file is sent with the name
  5517. OOFA.TXT.GZ, it is stored with that name, even after
  5518. decompression.
  5519. SET RECEIVE FILTER gunzip -c > \v(filename)
  5520. RECEIVE \flower(\fsubstring(\v(filename),1,\flength(\v(filename))-3))
  5521. Like the previous example, but the resulting filename has its
  5522. rightmost three characters removed from it and the remainder is
  5523. lowercased. So if the incoming filename is OOFA.TXT.GZ, it is
  5524. stored as oofa.txt after decompression.
  5525. Of course you don't want to type such long hideous commands, so we have
  5526. also introduced several new functions:
  5527. \fstripx(string[,character])
  5528. This function removes the rightmost segment of the string that
  5529. starts with the given character. If no character is given,
  5530. period (.) is used. Thus it is most conveniently used for
  5531. stripping the extension from a filename (or the decimal portion
  5532. from a floating-point number written in US/UK style). Examples:
  5533. \fstripx(OOFA.TXT.GZ) => OOFA.TXT
  5534. \fstripx(OOFA.TXT.GZ,.) => OOFA.TXT
  5535. \fstripx(OOFA.TXT.GZ,X) => OOFA.T
  5536. \fstripx(\fstripx(OOFA.TXT.GZ)) => OOFA
  5537. \fstripx($100.00) => $100
  5538. \fstripn(string,number)
  5539. Removes the rightmost number characters from the string.
  5540. Examples:
  5541. \fstripn(OOFA.TXT.GZ) => OOFA.TXT.GZ
  5542. \fstripn(OOFA.TXT.GZ,3) => OOFA.TXT
  5543. \fstripn(OOFA.TXT.GZ,7) => OOFA
  5544. \fstripb(string[,c1[,c2]])
  5545. Strips enclosing matching braces, brackets, parentheses, or
  5546. quotes from the string. The second argument, c1, specifies which
  5547. kind of enclosure to look for; if not specified, any enclosing
  5548. (), [], <>, {}, "", '', or `' are removed. If c1 is specified
  5549. and c2 is not, then if c1 is an opening brace, bracket, or
  5550. parenthesis, the matching closing one is supplied automatically
  5551. as c2. If both c1 and c2 are specified, then to be stripped the
  5552. string must begin with c1 and end with c2. If the string is not
  5553. enclosed in the indicated manner, the result is the original
  5554. string. Examples:
  5555. \fstripb("abc") => abc
  5556. \fstripb([abc]) => abc
  5557. \fstripb([abc) => [abc
  5558. \fstripb(<abc>) => abc
  5559. \fstripb(<abc>,[) => <abc>
  5560. \fstripb((abc)) => abc
  5561. \fstripb((abc),[) => (abc)
  5562. \fstripb((abc),{(}) => abc
  5563. \fstripb(+abc+) => +abc+
  5564. \fstripb(+abc+,+) => abc
  5565. \fstripb(+abc+,+,^) => +abc+
  5566. \fstripb(+abc^,+,^) => abc
  5567. \fstripb('abc') => abc
  5568. \fstripb(`abc') => abc
  5569. \fstripb(``abc'') => `abc'
  5570. \fstripb(\fstripb(``abc'')) => abc
  5571. Notice the special syntax required for including a literal
  5572. parenthesis in the argument list. As the last two examples
  5573. illustrate, \fstripb() strips only one level at at a time;
  5574. nesting can be used to strip a small fixed number of levels;
  5575. loops can be used to strip larger or indeterminate numbers of
  5576. levels.
  5577. \flop(string[,char])
  5578. Removes the leftmost segment of the string that ends with the
  5579. given character. If no character is given, period (.) is used.
  5580. Examples:
  5581. \flop(OOFA.TXT.GZ) => TXT.GZ
  5582. \flop(OOFA.TXT.GZ,.) => TXT.GZ
  5583. \flop(OOFA.TXT.GZ,X) => T.GZ
  5584. To remove the leftmost number characters, just use
  5585. \fsubstring(s,number+1). To return the rightmost number
  5586. characters, use \fright(s,number).
  5587. So the hideous example:
  5588. receive \flower(\fsubstring(\v(filename),1,\flength(\v(filename))-3))
  5589. can now be written as:
  5590. receive \flower(\fstripx(\v(filename)))
  5591. That is, the filename stripped of its extension and then lowercased.
  5592. This is not only shorter and less hideous, but also does not depend on
  5593. the length of the extension being 3.
  5594. Note that when a receive filter is in effect, this overrides your FILE
  5595. COLLISION setting, since Kermit has no way of knowing what the final
  5596. destination filename will be (because it does not know, and can not be
  5597. expected to know, the syntax of every version of every command shell on
  5598. every platform on the planet).
  5599. 4.2.4. Implicit Use of Pipes
  5600. If you wish, C-Kermit can also examine incoming filenames to see if
  5601. they start with "!", and if so, the subsequent text is treated as a
  5602. command to read from or write to. For example, if a Kermit client is
  5603. given the following command:
  5604. get {!finger | sort}
  5605. the server on the other end, if it supports this feature, will run the
  5606. "finger" program, pipe its standard output to the "sort" program, and
  5607. send sort's standard output back to you. Similarly, if you:
  5608. send oofa.txt !sort -r > oofa.new
  5609. or, equivalently:
  5610. send oofa.txt {!sort -r > oofa.new}
  5611. or:
  5612. send /as-name:{!sort -r > oofa.new} oofa.txt
  5613. this has the receiver send the contents of the incoming oofa.txt file
  5614. to the sort program, which sorts the text in reverse order and stores
  5615. the result in oofa.new.
  5616. This use of the exclamation mark should be familiar to UNIX users as
  5617. the "bang" feature that lets you run an external application or command
  5618. from within another application.
  5619. Kermit's "bang" feature is disabled by default, since it is not unheard
  5620. for filenames to actually begin with "!". So if you want to use this
  5621. feature, you must enable it with the following command:
  5622. SET TRANSFER PIPES { ON, OFF }
  5623. ON enables the recognition of "!" notation in incoming filenames
  5624. during file transfer as an indicator that the remaining text is
  5625. the name of a command. OFF, the default, disables this feature
  5626. and uses the text as a filename in the normal fashion. This
  5627. command does NOT affect SEND /COMMAND, GET /COMMAND, CSEND, etc.
  5628. So using a combination of CSEND (SEND /COMMAND) and the "bang" feature,
  5629. you can transfer a directory tree all in one command (assuming the
  5630. remote Kermit supports pipe transfers and has them enabled):
  5631. CSEND {tar cf - . | gzip -c} {!gunzip -c | tar xf -}
  5632. or:
  5633. SEND /COMMAND:{tar cf - . | gzip -c} /as:{!gunzip -c | tar xf -}
  5634. Pay close attention to the syntax. Braces are needed around the command
  5635. because it contains spaces; braces are needed around the as-name
  5636. because it ends with "-". The as-name must begin with "!" or receiving
  5637. Kermit will not recognize it as a command. The CSEND command must NOT
  5638. begin with "!" unless you are running a command whose name really does
  5639. start that character.
  5640. Similarly, you have a Kermit server send a directory tree to be
  5641. unpacked on the client end:
  5642. CGET {!tar cf - . | gzip -c} {gunzip -c | tar xf -}
  5643. or:
  5644. GET /COMMAND {!tar cf - . | gzip -c} /as:{gunzip -c | tar xf -}
  5645. Notice how, in this case, the bang is required in the remote command,
  5646. to distinguish it from a filename, but not in the local command, since
  5647. by definition of CGET (or GET /COMMAND), it is known to be a command.
  5648. SEND and RECEIVE FILTERs supersede the bang feature. For example, if a
  5649. file arrives under the name "!gunzip -c | tar xf -", but the receiving
  5650. Kermit also has been given a command like:
  5651. set receive filter sort -r > \v(filename)
  5652. then the incoming data will be sorted rather than gunzipped.
  5653. Finally, if SET TRANSFER PIPES is ON (and in this case, this must be
  5654. done in your C-Kermit initialization file), you can send from a pipe on
  5655. the C-Kermit command line:
  5656. kermit -s "!finger | sort -r" -a userlist
  5657. In this case the "filename" contains spaces and so must be quoting
  5658. using your shell's quoting rules.
  5659. 4.2.5. Success and Failure of Piped Commands
  5660. Commands or programs started by Kermit as a result of CSEND or CRECEIVE
  5661. commands, CGET, SEND /COMMAND, REDIRECT commands (seeSection
  5662. 4.2.8.2), implicit use of pipes, RUN commands, and so forth, should
  5663. return their exit status codes to the Kermit command that caused them
  5664. to be run, and therefore IF SUCCESS and IF FAILURE tests after these
  5665. commands should work as expected. For example:
  5666. CSEND blah < filename
  5667. should fail if there is no command called "blah" or if there is no file
  5668. called "filename". However, this is not foolproof and sometimes
  5669. C-Kermit might think a command succeeded when it failed, or vice versa.
  5670. This is most likely to happen when the highly system-dependent methods
  5671. that Kermit must use to determine a command's exit status code do not
  5672. supply the right information.
  5673. It can also happen because some commands might define success and
  5674. failure differently from what you expect, or because you are using a
  5675. pipeline composed of many commands, and one of them fails to pass
  5676. failing exit status codes up the chain. The most likely culprit is the
  5677. shell itself, which in most cases must be interposed between Kermit and
  5678. any external program to be run.
  5679. In any case, you can examine the following variable to find out the
  5680. exit status code returned to Kermit by the process most recently run by
  5681. any command that runs external commands or programs, including CSEND,
  5682. CRECEIVE, REDIRECT, RUN, etc:
  5683. \v(pexitstat)
  5684. In UNIX, Windows and OS/2, the value should be -2 if no command has
  5685. been run yet, 0 if the most recent command succeeded, -1, -3, or -4 if
  5686. there was an internal error, and a positive number returned by the
  5687. command itself if the command failed. If the number is in the range
  5688. 1-127, this is the program's exit status code. If it is 128 or greater,
  5689. this is supposed to indicate that the command or program was
  5690. interrupted or terminated from outside itself.
  5691. In Windows 95 and 98, the return values of the default shell are
  5692. unreliable; various third-party shells can be used to work around this
  5693. deficiency.
  5694. In VMS, it is the actual exit status code of the command that was run.
  5695. This is an odd number if the command succeeded, and an even number if
  5696. it failed. You can see the associated message as follows:
  5697. run write sys$output f$message(\v(pexitstat))
  5698. Or, more conveniently, use the new Kermit function:
  5699. echo \ferrstring(\v(pexitstat))
  5700. which converts a system error code (number) to the corresponding
  5701. message.
  5702. 4.2.6. Cautions about Using Pipes to Transfer Directory Trees
  5703. Although utilities such as tar and zip/unzip might be available on
  5704. different platforms (such as UNIX and Windows), this does not
  5705. necessarily mean you can use them successfully to transfer directory
  5706. trees between unlike platforms. For example:
  5707. CSEND {tar cf - . | gzip -c} {!gunzip -c | tar xf -}
  5708. when used from UNIX to Windows will have satisfactory results for
  5709. binary files, but not for text files. UNIX text files have lines ending
  5710. with Linefeed (LF) only, whereas Windows text files have lines ending
  5711. in Carriage Return and Linefeed (CRLF). Thus any text files that were
  5712. in the archive formed by the first tar command will be unpacked by the
  5713. second tar command in their original form, and will display and print
  5714. incorrectly in Windows (except in applications that have been
  5715. explicitly coded to handle UNIX-format text files). On the other hand
  5716. if you told gzip to use "text mode" to do record format conversion
  5717. (assuming there was a way to tell it, as there is with most "zip"
  5718. programs), this would destroy any binary files in the archive.
  5719. Furthermore, if the archive contains text files that are written in
  5720. languages other than English, the "special" (accented and/or non-Roman)
  5721. characters are NOT translated, and are therefore likely show up as
  5722. gibberish on the target system. For example, West European languages
  5723. are usually encoded in ISO Latin Alphabet 1 in UNIX, but in PC code
  5724. page 850 on the PC. Capital A with acute accent is code point 193
  5725. (decimal) Latin-1, but 181 in CP850. So A-acute in the UNIX file
  5726. becomes Middle Box Bottom on the PC, and similarly for all the other
  5727. special characters, and for all other languages -- Greek, Russian,
  5728. Hebrew, Japanese, etc.
  5729. So when transferring text files between unlike platforms, you should
  5730. use direct Kermit file transfers so Kermit can apply the needed
  5731. record-format and character-set transformations. Use pipelines
  5732. containing archivers like tar or zip only if all the files are binary
  5733. or the two systems use the same record format and character set for
  5734. text files.
  5735. Also seeSections 4.3,4.10,4.11, and4.15 for how
  5736. to transfer directory trees between both like and unlike systems
  5737. directly with Kermit.
  5738. 4.2.7. Pipes and Encryption
  5739. Of course pipelines could be used for encrypted file transfers,
  5740. assuming proper precautions could be taken concerning the transmission
  5741. of the key. But there is rarely a good way to do this. To illustrate
  5742. using UNIX crypt:
  5743. csend {crypt key < filename} {!crypt key > filename}
  5744. Or, more ambitiously:
  5745. csend {tar cf - . | gzip -c | crypt key} {!crypt key | gunzip -c | tar xf -}
  5746. transmits the key in the file header packet as part of the (clear-text)
  5747. remote command, defeating the entire purpose of encrypting the file
  5748. data.
  5749. But if you are connected in terminal mode to the remote computer and
  5750. type:
  5751. creceive {crypt key > filename}
  5752. at the remote Kermit prompt, you have also transmitted the key in clear
  5753. text over the communications link.
  5754. At present, the only secure way to use CSEND and CRECEIVE with an
  5755. encryption filter is to have a human operator at both ends, so the key
  5756. does not have to be transmitted.
  5757. Theoretically it would be possible to use PGP software (Pretty Good
  5758. Privacy, by Phil Zimmerman, Phil's Pretty Good Software) to avoid key
  5759. transmission (since PGP uses separate public and private key and "lets
  5760. you communicate securely with people you've never met, with no secure
  5761. channels needed for prior exchange of keys"), but the specific method
  5762. has yet to be worked out.
  5763. HINT: See the PGP User's Guide, e.g. at:
  5764. http://www.telstra.com.au/docs/PGP/
  5765. Especially the topic "Using PGP as a UNIX-Style Filter":
  5766. http://www.telstra.com.au/docs/PGP/pgpdoc2/pgpdoc2_17.html
  5767. In any case, better and more convenient security options are now
  5768. available: Kerberos authentication and encryption and the new
  5769. ability to run C-Kermit "though" other communication programs,
  5770. described in Section 2.7.
  5771. 4.2.8. Commands and Functions Related to Pipes
  5772. 4.2.8.1. The OPEN !READ and OPEN !WRITE Commands
  5773. These are described inUsing C-Kermit, and are generally useful
  5774. with reading output from commands that produce more than one line on
  5775. their standard output, or writing multiple lines into commands that
  5776. accept them on their standard input.
  5777. In C-Kermit 7.0 CLOSE !READ is accepted as a synonym for CLOSE READ,
  5778. and CLOSE !WRITE for CLOSE WRITE.
  5779. Testing the success and failure of these commands, however, can be a
  5780. bit tricky. Consider:
  5781. open !read lalaskjfsldkfjsldkfj
  5782. (where "lalaskjfsldkfjsldkfj" is neither a valid command nor the name
  5783. of a program or script that can be run). OPEN !READ, in UNIX at least,
  5784. translates this into execl(shellpath,shellname,"-c",command). This
  5785. means it starts your preferred shell (e.g. from the SHELL environment
  5786. variable) and asks it to execute the given command. It must be this
  5787. way, because your command can be a either an internal shell command
  5788. (which only your shell can execute) or an external command, which only
  5789. your shell knows how to find (it knows your PATH and interprets, etc).
  5790. Therefore unless OPEN !READ can't start your shell, it always succeeds.
  5791. Continuing with the nonexistent-command example:
  5792. C-Kermit> open !read lalaskjfsldkfjsldkfj
  5793. C-Kermit> status
  5794. SUCCESS
  5795. C-Kermit> read line
  5796. C-Kermit> status
  5797. SUCCESS
  5798. C-Kermit> echo "\m(line)"
  5799. "bash: lalaskjfsldkfjsldkfj: command not found"
  5800. C-Kermit> close read
  5801. C-Kermit> status
  5802. FAILURE
  5803. C-Kermit>
  5804. In other words, the failure can not be detected on OPEN, since the OPEN
  5805. command succeeds if it can start your shell. It can't be detected on
  5806. READ, since all this does is read output from the shell, which in this
  5807. case happens to be an error message. However, failure IS detected upon
  5808. close, since this is the occasion upon which the shell gives Kermit its
  5809. exit status code.
  5810. For an illustration of this situation, see Section 2.14.
  5811. 4.2.8.2. The REDIRECT Command
  5812. A second method of I/O redirection is offered by the REDIRECT command.
  5813. This is a rather advanced and tricky feature that is presently
  5814. supported only in UNIX C-Kermit, in OS-9 C-Kermit, and in Kermit 95.
  5815. Syntax:
  5816. REDIRECT command
  5817. Runs the given command, sending its standard output to the
  5818. current communications channel (SET LINE, SET PORT, or SET HOST
  5819. connection), and reading its standard input from the same
  5820. connection. Works only in local mode -- i.e. a connection is
  5821. required -- and then only if the given command uses Standard
  5822. I/O.
  5823. Example:
  5824. redirect finger
  5825. runs the local "finger" command and sends its output over the
  5826. connection as plain text, where presumably there is a process set up to
  5827. read it. Another example:
  5828. redirect finger | sort -r
  5829. shows the use of a pipeline.
  5830. Note: REDIRECT differs from CSEND/CRECEIVE in two important ways: (1)
  5831. it does not use the Kermit protocol, and (2) it uses a bidirectional
  5832. pipe rather than a one-way pipe.
  5833. The primary use of the REDIRECT command is to run external protocols,
  5834. such as sz/rz in UNIX for ZMODEM, when they work over Standard I/O(*).
  5835. Example:
  5836. set host xyzcorp.com
  5837. (login, etc)
  5838. redirect sz oofa.zip
  5839. lets you make a Telnet connection with C-Kermit and then do a ZMODEM
  5840. transfer over it. ZMODEM protocol messages go both ways over the same
  5841. connection simultaneously.
  5842. It is possible to use C-Kermit on UNIX as your PPP dialer and then to
  5843. REDIRECT the connection to the PPP software, but C-Kermit 7.0 offers a
  5844. better approach to PPP dialing in its new EXEC command (Section
  5845. 1.23).
  5846. In theory, you can also redirect an interactive process. For example,
  5847. suppose you tell Kermit 95 to wait for an incoming TCP/IP connection:
  5848. set host * 3000
  5849. and then tell C-Kermit on UNIX to:
  5850. set host kermit95hostname 3000
  5851. redirect ksh
  5852. and then tell Kermit 95 to CONNECT: now you are talking to the UNIX
  5853. K-shell; you can give commands (pwd, ls, etc) and see the results. In
  5854. practice, the K-shell's terminal modes are messed up because (a) it is
  5855. not going through the Unix terminal driver, and (b) it is "smart" and
  5856. knows it is being redirected, and so acts in a decidedly inhospitable
  5857. manner (other applications like EMACS, vi, etc, simply refuse to run if
  5858. their standard i/o has been redirected).
  5859. (*) The publicly-distributed sz/rz programs do not work as clients.
  5860. However, Omen Technology does offer an up-to-date redirectable
  5861. client XYZMODEM program called crzsz.
  5862. 4.2.8.3. Receiving Mail and Print Jobs
  5863. As of 7.0, and in UNIX only, files that are sent to C-Kermit as mail
  5864. (when the other Kermit uses a MAIL or SEND /MAIL command) or to be
  5865. printed (via REMOTE PRINT or SEND /PRINT) are now piped directly to the
  5866. mail or print program, rather than written to temporary files and then
  5867. mailed or printed and then deleted. This has the advantages of (a) not
  5868. requiring a temporary file, and (b) allowing mail to have a proper
  5869. subject in place of the filename. Temporary files were bad not only
  5870. because they required (a) space, and (b) writability of the current
  5871. directory, but also because using them could result in wiping out an
  5872. existing file. See Section 4.7 for more about SEND /MAIL and SEND
  5873. /PRINT.
  5874. 4.2.8.4. Pipe-Related Functions
  5875. The \fcommand(command) function runs the given shell or system command
  5876. and returns the command's standard output as its value (with any
  5877. newline characters stripped from the end), unless the result is too
  5878. long, in which case it returns the empty string. The maximum length for
  5879. the result is at least 1022 bytes, and it might be longer on some
  5880. platforms. Examples (UNIX):
  5881. C-Kermit> echo "\fcommand(date)"
  5882. "Fri Apr 18 13:31:42 1997"
  5883. C-Kermit> echo "\fcommand(finger | wc -l)" ; how many users logged in?
  5884. " 83"
  5885. C-Kermit> evaluate \fcommand(finger | wc -l) * 2
  5886. 166
  5887. C-Kermit> echo Welcome to \fcommand(tty) on \fcommand(date)
  5888. Welcome to /dev/ttyre on Fri Apr 18 13:31:42 1997
  5889. C-Kermit> echo "\fcommand(ls oofa.*)"
  5890. "oofa.c
  5891. oofa.h
  5892. oofa.o"
  5893. C-Kermit> cd /directory-with-thousands-of-files
  5894. C-Kermit> echo "\fcommand(ls -l)" ; This would be too long
  5895. ""
  5896. C-Kermit>
  5897. If a command's output would be too long, you can use the other, more
  5898. laborious method of reading from a command: OPEN !READ command, READ
  5899. each line, CLOSE !READ.
  5900. The \frawcommand(command) function is identical to \fcommand(command),
  5901. except it does not remove trailing newline characters:
  5902. C-Kermit> echo "\frawcommand(date)"
  5903. "Fri Apr 18 13:31:42 1997
  5904. "
  5905. C-Kermit> echo "\frawcommand(ls oofa.*)"
  5906. "oofa.c
  5907. oofa.h
  5908. oofa.o
  5909. "
  5910. C-Kermit>
  5911. Use \frawcommand() if you want to retain the final line terminators, or
  5912. if the command's output is "binary". But remember that if the result of
  5913. this (or any other) function contains any NUL (ASCII code 0)
  5914. characters, the first NUL will terminate the result string because this
  5915. is how C strings work (it's "C-Kermit", remember?).
  5916. These functions are useful not only locally, but also in the
  5917. client/server arena. If you need to get the results from a system
  5918. command on the server end into a variable on the client end, just do:
  5919. [ remote ] query kermit command(date)
  5920. The result is in the local \v(query) variable; seeUsing C-Kermit,
  5921. 2nd Ed., pp.359-360 for details.
  5922. 4.3. Automatic Per-File Text/Binary Mode Switching
  5923. When transferring files between like systems (e.g. UNIX-to-UNIX),
  5924. binary mode can be used for all files unless character-set translation
  5925. is needed, and in fact Kermit programs of recent vintage recognize each
  5926. others' platforms and switch to binary mode automatically when it is
  5927. appropriate (e.g. DOS to OS/2, or UNIX to UNIX). (Exception: LABELED
  5928. mode is chosen for VMS-to-VMS and OS/2-to-OS/2 transfers so complex
  5929. file formats can be preserved.)
  5930. On a client/server connection between like systems, the transfer mode
  5931. is currently determined by the file sender, rather than always by the
  5932. client. If the client is sending, it controls the transfer mode. If a
  5933. GET command is sent to the server, the server sends all files in binary
  5934. mode if its TRANSFER CHARACTER-SET is TRANSPARENT; otherwise it uses
  5935. text mode for text files (according to its text-pattern list) and
  5936. binary mode for binary files. Of course, the client can control the
  5937. server's transfer character-set with the REMOTE SET TRANSFER
  5938. CHARACTER-SET command.
  5939. When transferring files between unlike systems, however, (e.g.
  5940. UNIX-to-DOS), some files (such as executable program images) must be
  5941. transferred in binary mode but others (such as plain-text files) must
  5942. be transferred in text mode so their record format and character sets
  5943. can be appropriately converted. If a binary file is transferred in text
  5944. mode, it is ruined. If a text file is transferred in binary mode, then
  5945. at the very least, its format can be incorrect; at worst it is also
  5946. corrupted because its character set was not converted (in extreme cases
  5947. the corruption is total, e.g. because one system is ASCII-based and the
  5948. other EBCDIC).
  5949. 4.3.1. Exceptions
  5950. VMS C-Kermit, when sending files to a non-VMS system, switches to text
  5951. or binary mode automatically for each file, based on the record format
  5952. in the file's directory entry; thus the mechanisms described in this
  5953. section do not apply to VMS C-Kermit, yet the effect is the same:
  5954. automatic text/binary mode switching when VMS C-Kermit is sending
  5955. files. See the VMS Appendix ofUsing C-Kermit for details.
  5956. Kermit versions that support LABELED or IMAGE transfer mode are
  5957. likewise not affected by this feature when one of those modes is
  5958. selected (normally used only when transferring between like systems).
  5959. Kermit versions that support file-transfer pipes and filters are not
  5960. affected by this feature when pipes or filters are used, since the
  5961. output of a pipe or filter (such as gzip) is likely to require transfer
  5962. in a different mode than the original file.
  5963. Finally, SEND /TEXT or SEND /BINARY will force files to be sent in the
  5964. indicated mode, overriding all automatic transfer-mode-choosing
  5965. mechanisms.
  5966. 4.3.2. Overview
  5967. Suppose you give C-Kermit a command like:
  5968. SEND *.*
  5969. And suppose the pattern *.* matches a mixture of text files (such as
  5970. program source code) and binary files (such os object modules or
  5971. executable programs).
  5972. C-Kermit 6.0 and earlier (except on VMS) send all files in the same
  5973. mode: whatever you said in your most recent SET FILE TYPE command, or
  5974. else whatever mode was chosen automatically according to the rules on
  5975. page 236 of Using C-Kermit, 2nd Ed.
  5976. But when text and binary files are mixed in the same group, and the
  5977. files are being transferred to an unlike system (e.g. UNIX to IBM
  5978. Mainframe), this results in corruption of either all the text files or
  5979. all the binary files.
  5980. Stream-oriented file systems such as in UNIX and DOS do not record any
  5981. information about the file to tell us whether the file should be
  5982. transferred in binary or text mode, making it impossible to select the
  5983. transfer mode for each file in a group automatically with any
  5984. certainty.
  5985. However, we can use some fairly-well established file naming
  5986. conventions for this purpose. C-Kermit 7.0 lets you provide lists of
  5987. filename patterns that are used to separately determine the file type
  5988. for each individual file being transferred. A pattern is a string,
  5989. possibly containing the special characters "*" (asterisk, which matches
  5990. any string of zero of more characters) and/or "?" (question mark, which
  5991. matches any single character). For example "a*b" matches all files
  5992. whose names start with "a" and end with "b", such as "ab", "arb",
  5993. "ababababab", etc, but not "abba". And "a?b" matches any file whose
  5994. name starts with "a", ends with "b", and is exactly 3 characters long.
  5995. NOTE: When typing commands at the C-Kermit prompt, you must prefix
  5996. "?" with \ to override its normal function of giving help.
  5997. (Also see Section 4.9 for additional pattern-matching notations
  5998. that might be available in your version of C-Kermit.)
  5999. When you have specified filename recognition patterns, C-Kermit can
  6000. transfer the ones whose names match any of the binary-mode patterns in
  6001. binary mode, and those with names that match any of the text-mode
  6002. patterns in text mode, and those whose names match neither in the
  6003. prevailing mode you have chosen, or that was chosen automatically via
  6004. peer recognition.
  6005. 4.3.3. Commands
  6006. SET FILE PATTERNS { ON, OFF, AUTO }
  6007. This tells Kermit whether to do per-file filename
  6008. pattern-matching to determine text or binary mode. The normal
  6009. and default setting is AUTO, which means to use pattern lists to
  6010. switch transfer mode only when it is certain that the other
  6011. Kermit program supports automatic notification of transfer mode
  6012. (via Attribute packets) on a per-file basis (this information is
  6013. obtained automatically during protocol startup negotiation). ON
  6014. means to always determine the transfer mode from the filename
  6015. and pattern list when sending files. Use OFF to disable this
  6016. feature (without resetting your pattern lists). Also note that
  6017. if you have selected LABELED file transfer (SET FILE TYPE
  6018. LABELED), this takes precedence over filename-matching patterns
  6019. and all files are sent in labeled mode.
  6020. SET TRANSFER MODE MANUAL
  6021. Disables the use of filename patterns, no matter what the FILE
  6022. PATTERNS setting.
  6023. REMOTE SET TRANSFER MODE MANUAL
  6024. Client command to disable automatic transfer mode, and therefore
  6025. also filename patterns, in the server. Synonym: REMOTE SET XFER
  6026. MODE MANUAL.
  6027. { GET, SEND, etc } { /BINARY, /TEXT }
  6028. Including a /BINARY or /TEXT (or, where supported, /IMAGE or
  6029. /LABELED) switch with a file-transfer command changes the
  6030. transfer mode to manual for that command only, and therefore
  6031. disables patterns that that command.
  6032. SET FILE BINARY-PATTERNS [ pattern [ pattern [ pattern ... ] ] ]
  6033. A list of zero or more patterns, separated by spaces (not
  6034. commas). Letters in a pattern are case-sensitive if the
  6035. underlying filenames are case sensitive (as in UNIX), and
  6036. case-insensitive otherwise (as in Windows). If a file's name is
  6037. matched by any pattern in the list and SET FILE PATTERNS is ON,
  6038. the file is sent in binary mode. Examples:
  6039. SET FILE BINARY-PATTERNS *.gz *.Z *.tar *.zip *.o *.so *.a *.out ; UNIX
  6040. SET FILE BINARY-PATTERNS *.EXE *.ZIP *.OBJ *.COM ; DOS or OS/2 or Windows
  6041. If a pattern contains spaces, enclose it in braces.
  6042. SET FILE TEXT-PATTERNS [ pattern [ pattern [ pattern ... ] ] ]
  6043. Like SET FILE BINARY-PATTERNS, but the patterns choose text
  6044. files rather than binary ones. Examples:
  6045. SET FILE TEXT-PATTERNS *.TXT *.KSC *.HTM* *.BAT ; DOS, Windows, OS/2
  6046. ADD BINARY-PATTERNS [ pattern [ pattern [ pattern ... ] ] ]
  6047. Adds one or more patterns to the BINARY-PATTERN list.
  6048. ADD TEXT-PATTERNS [ pattern [ pattern [ pattern ... ] ] ]
  6049. Adds one or more patterns to the TEXT-PATTERN list.
  6050. REMOVE BINARY-PATTERNS [ pattern [ pattern [ pattern ... ] ] ]
  6051. Removes one or more patterns from the BINARY-PATTERN list. The
  6052. given patterns are matched with the ones in the BINARY-PATTERNS
  6053. list with case sensitivity if the underlying file system has
  6054. case-sensitive names (as do UNIX and OS-9), otherwise with case
  6055. independence.
  6056. REMOVE TEXT-PATTERNS [ pattern [ pattern [ pattern ... ] ] ]
  6057. Removes one or more patterns from the TEXT-PATTERN list.
  6058. SHOW PATTERNS
  6059. Displays the current pattern selections.
  6060. Whenever you give a SET FILE BINARY-PATTERNS or SET FILE TEXT-PATTERNS
  6061. command, the previous list is replaced. If you give one of these
  6062. commands without a pattern list, the previous list is removed.
  6063. When patterns are active and files are being sent, text patterns (if
  6064. any) are applied first (but only if not RESENDing and not sending in
  6065. LABELED mode), then binary patterns, so if the same pattern appears in
  6066. both lists, binary mode is chosen.
  6067. 4.3.4. Examples
  6068. Here's an example that might be used when sending files from UNIX:
  6069. set file type binary
  6070. set file text-patterns *.c *.h *.w *.txt makefile
  6071. set file binary-patterns *.o
  6072. msend makefile wermit wart ck*.[cwho] ck*.txt
  6073. Note that "wermit" and "wart" do not match any patterns so they are
  6074. sent in the prevailing mode, which is binary. Also note the use of
  6075. "makefile" as a pattern that does not contain any wildcard characters
  6076. (there is no other convention to distinguish among "wermit" and "wart",
  6077. which are binary executables, and "makefile", which is a text file,
  6078. purely by their names).
  6079. Most C-Kermit implementations have a default pattern list built in,
  6080. which includes patterns that are almost certain to succeed in picking
  6081. the right transfer mode. Others are omitted due to ambiguity. For
  6082. example ".hlp", and ".ini" are generally binary types in Windows but
  6083. text types everywhere else.
  6084. NOTE: ".doc", used for decades to denote plain-text documentation
  6085. files, now more often than not denotes a Microsoft Word Document, so
  6086. ".doc" is now considered a binary type since it does less harm to
  6087. transfer a plain-text document in binary mode than it does to
  6088. transfer an MS Word file in text mode (except when IBM mainframes
  6089. are involved!)
  6090. ANOTHER NOTE: ".com" files are binary in DOS-like operating systems,
  6091. but they are text (DCL command procedures) in VMS. VMS C-Kermit
  6092. sends .COM files in text mode; K95 sends them in binary mode. If you
  6093. download a .COM file from VMS to DOS or Windows, and then upload it
  6094. to another VMS system, be sure to use SEND /TEXT to preserve its
  6095. textness.
  6096. You can see the default pattern list by starting C-Kermit without its
  6097. initialization file (e.g. "kermit -Y") and using the SHOW PATTERNS
  6098. command. If you will be depending on this feature, be sure to examine
  6099. the list carefully in conjunction with the applications that you use.
  6100. The default pattern list does not take "backup files" into account
  6101. because (a) people usually don't want to transfer them; and (b) it
  6102. would make the pattern lists more than twice as long. For example, we
  6103. would need to include both *.txt and *.txt.~[0-9]*~ for ".txt" files,
  6104. and similarly for all the others. Instead, you can use SEND /NOBACKUP
  6105. (or SET SEND BACKUP OFF) to skip over all backup files.
  6106. Put your most commonly-used safe pattern declarations in your C-Kermit
  6107. customization file (ckermod.ini, .mykermrc, k95custom.ini, etc).
  6108. As noted, SET FILE PATTERNS is ON by default. Sometimes, however, it is
  6109. desirable, or necessary, to force files to be sent in a particular
  6110. mode, and often this must be done from the command line (e.g. when
  6111. using Kermit as a download helper in a Web browser like Lynx). The -V
  6112. command-line options is equivalent to SET FILE PATTERNS OFF and SET
  6113. TRANSFER MODE MANUAL. Example:
  6114. kermit -Vis oofa.txt
  6115. forces oofa.txt to be sent in binary mode, even though ".txt" might
  6116. match a text pattern.
  6117. 4.4. File Permissions
  6118. "Permissions" refers to a code associated with a file that specifies
  6119. who is allowed to access it, and in what manner. For example, the
  6120. owner, the members of one or more groups, the system administrator, and
  6121. everybody else, might be allowed various combinations of Read, Write,
  6122. Append, Execute, or Listing access.
  6123. The permission code goes by different names on different platforms. In
  6124. UNIX, it might be called the filemode. In VMS, it is called the file
  6125. protection (or protection mask).
  6126. The comments in this section presently apply only to the UNIX and VMS
  6127. versions of C-Kermit, to which these features were added in version
  6128. 7.0; the DOS, Windows, and OS/2 file systems embody no notions of
  6129. protection, and so MS-DOS Kermit and Kermit 95 do not send file
  6130. permissions, and ignore them when received.
  6131. The permissions for a received file are determined by a combination of
  6132. the file transfer mode (VMS-to-VMS transfers only), whether a file of
  6133. the same name exists already, whether permissions of the file are
  6134. received in the file attribute packet, and the setting of ATTRIBUTES
  6135. PROTECTION.
  6136. The default for ATTRIBUTES PROTECTION is ON. If no attributes are
  6137. received, the effect is the same as if attributes PROTECTION were OFF.
  6138. For VMS-to-VMS transfers, the default LABELED mode simply copies the
  6139. protection code from source to destination.
  6140. 4.4.1. When ATTRIBUTES PROTECTION is OFF
  6141. If no file of the same name exists, system defaults determine the
  6142. permissions of the new file. Otherwise, the actions taken depend on the
  6143. current FILE COLLISION setting: BACKUP, OVERWRITE, RENAME, etc, as
  6144. documented inUsing C-Kermit. But now the new file (if it is
  6145. created at all) automatically inherits the permissions (mode bits) of
  6146. the existing file in a way that is appropriate for the platform.
  6147. 4.4.1.1. Unix
  6148. All mode bits are inherited except the directory bit, since the
  6149. incoming file can not possibly be a directory. (In any case, it is not
  6150. possible to receive a file that has the same name as an existing
  6151. directory unless FILE COLLISION is set to RENAME).
  6152. 4.4.1.2. VMS
  6153. Files with the same name as an existing file, transferred in modes
  6154. other than LABELED between VMS systems, inherit the protection of the
  6155. prior version.
  6156. 4.4.2 When ATTRIBUTES PROTECTION is ON
  6157. File permissions can be conveyed as part of the file transfer process,
  6158. in accordance with the Kermit protocol definition. If the file sender
  6159. puts system-dependent and/or system-independent versions of the file
  6160. protection (permissions) into the Attribute (A) packet, the file
  6161. receiver can set the new file's permissions from them. Otherwise, the
  6162. permissions are set the same as for ATTRIBUTES PROTECTION OFF.
  6163. When the incoming A packet contains system-dependent permissions, the
  6164. file receiver checks to see if the sender has the same system ID (e.g.
  6165. both the sending and receiving systems are UNIX, or both are VMS); if
  6166. so, it decodes and uses the system-dependent permissions; otherwise it
  6167. uses the generic ones (if any) and applies them to the owner field,
  6168. setting the other fields appropriately as described in the following
  6169. sections.
  6170. Setting the incoming file's protection from the A packet is controlled
  6171. by SET ATTRIBUTES PROTECTION (or PERMISSION), which is ON by default,
  6172. and its status is displayed by SHOW ATTRIBUTES.
  6173. The main benefit of this feature is to not have to "chmod +x" an
  6174. executable file after transfer from UNIX to UNIX. Its cross-platform
  6175. benefits are less evident, perhaps to retain the status of the Unix 'x'
  6176. bit on a VMS system, for subsequent transfer back to a Unix system.
  6177. 4.4.2.1. System-Specific Permissions
  6178. System-specific file permissions are used when the two Kermit programs
  6179. recognize each other as running on the same type of system. For
  6180. example, both are running under some form of UNIX (it doesn't matter
  6181. which UNIX variation -- HP-UX, Solaris, AIX, etc -- all use the same
  6182. scheme for file permissions); or both are running under VMS (even if
  6183. one is on an Alpha and the other on a VAX, and/or one is old and the
  6184. other is new).
  6185. 4.4.2.1.1. UNIX
  6186. UNIX supports three categories of users, File Owner, Group, and World,
  6187. and three types of file access permission: Read, Write, and Execute.
  6188. Thus, a UNIX file's permissions are expressed in 9 bits.
  6189. The system-dependent permission string for UNIX is a 3-digit octal
  6190. string, the low-order 9 bits of the st_mode member of the stat struct;
  6191. we deliberately chop off the "file format" bits because they are not
  6192. permissions, nor do we convey the setuid/setgid bits, lock bit, sticky
  6193. bit, etc.
  6194. 4.4.2.1.2. VMS
  6195. VMS supports four categories of users, System, File Owner, Group, and
  6196. World, and four types of file access permission: Read, Write, Execute,
  6197. and Delete. Thus, a VMS file's permissions are expressed in 16 bits.
  6198. The system-dependent protection string for VMS is a 4-digit hexadecimal
  6199. string, corresponding to the internal-format protection word of the
  6200. file (RWED for each of World,Group,Owner,System). A new file normally
  6201. gets all 16 protection bits from the original file of the same name.
  6202. Note: VMS-to-VMS transfers take place in LABELED mode when the two
  6203. C-Kermits recognize each other's platform as VMS (unless you have
  6204. disabled LABELED-mode transfers). In this case, all of a file's
  6205. attributes are preserved in the transfer and the protection mask (and
  6206. other information) is taken from the file's internal information, and
  6207. this takes precedence over any information in the Attribute packets.
  6208. You can defeat the automatic switching into LABELED mode (if you want
  6209. to) with SET TRANSFER MODE MANUAL.
  6210. 4.4.2.2. System-Independent Permissions
  6211. The system-independent ("generic") protection is used when the system
  6212. IDs of the two Kermit programs do not agree (e.g. one is UNIX, the
  6213. other is VMS). The generic protection attribute includes the following
  6214. permissions (not all are applicable to every file system): Read, Write,
  6215. Append, Execute, Delete, Search. The generic permissions are derived
  6216. from the owner permissions of the source file, thus, a Unix 'w'
  6217. permission becomes VMS Write,Delete.
  6218. The Owner field of the new file's permissions is set from the incoming
  6219. generic protection attribute.
  6220. In UNIX, the Group and World permissions are set according to your
  6221. umask, except that execute permission is NOT set in these fields if it
  6222. was not also set in the generic protection (and consequently, is set in
  6223. the Owner field).
  6224. In VMS, the System, Group, and World permissions are set according to
  6225. the process default file permission (as shown in VMS by SHOW
  6226. PROTECTION), except that no permissions are allowed in these fields
  6227. that are not included in the generic permissions.
  6228. Note that the VMS and UNIX interpretations of Execute permission are
  6229. not identical. In UNIX, a file (binary executable, shell script, etc)
  6230. may not be executed unless it has Execute permission, and normally
  6231. files that are not intended for execution do not have Execute
  6232. permission. In VMS, Read permission implicitly supplies Execute
  6233. capability. Generally files that have Read permission also have
  6234. explicit Execute permission, but files (binary executables, DCL command
  6235. procedures) that have Read permission and not Execute permission can
  6236. still be executed.
  6237. 4.5. File Management Commands
  6238. 4.5.1. The DIRECTORY Command
  6239. Prior to C-Kermit 7.0, the DIRECTORY command always ran an external
  6240. system command (such as "ls" on UNIX) or program to product the
  6241. directory listing. This had certain advantages, mostly that you could
  6242. include system-dependent options for customized listings, e.g. on UNIX:
  6243. dir -lt c* | more
  6244. or in VMS:
  6245. directory /size/date/protection/except=*.obj oofa.*;0
  6246. This approach, however, carries some disadvantages: C-Kermit can't
  6247. return SUCCESS or FAILURE status for (e.g.) "dir foo" according to
  6248. whether the file "foo" exists; and it runs an inferior process, which
  6249. might be a problem in some environments for resource and/or security
  6250. reasons, and won't work at all in a "nopush" environment (e.g. one in
  6251. which C-Kermit is configured to forbid access to exterior commands and
  6252. programs, e.g. in a VMS "captive account").
  6253. In C-Kermit 7.0 on VMS and UNIX, and in K95 1.1.19 and later, the
  6254. DIRECTORY command is internal to Kermit. It can be run in a "nopush"
  6255. environment and returns SUCCESS or FAILURE status appropriately. In
  6256. UNIX it prints all dates and times in a consistent way (unlike ls). In
  6257. VMS it prints precise file sizes, rather than "blocks". It offers
  6258. several formatting and other options, but it is not necessarily more
  6259. flexible than the corresponding external commands or programs (the UNIX
  6260. "ls" program, the VMS "directory" command). The syntax is:
  6261. DIRECTORY [ switch [ switch [ ... ] ] ] [ filespec ]
  6262. If no filespec is given, all files in the current directory are listed.
  6263. Optional switches include all the standard file-selection switches
  6264. presented in Section 1.5.4, plus:
  6265. /ALL
  6266. Show both regular files and directories; this is the default.
  6267. /ARRAY:x
  6268. Instead of displaying a directory listing, put the files that
  6269. would have been shown (based on the filespec and other selection
  6270. switches) in the given array. The array need not (and should
  6271. not) be predeclared; if the array already exists, it is
  6272. destroyed and reused. The array name can be a single letter,
  6273. like "a", or any fuller form, such as "&a", "\&a", "\&a[]", etc.
  6274. If the /ARRAY switch is included, the following other switches
  6275. are ignored: /BRIEF, /VERBOSE, /HEADING, /PAGE, /ENGLISHDATE,
  6276. /ISODATE, /XFERMODE, /MESSAGE, /SORT, /REVERSE, /ASCENDING. In
  6277. other words, only file selection switches are meaningful with
  6278. /ARRAY: /FILES, /DIRECTORIES, /ALL, /DOTFILES, /NOBACKUP,
  6279. /RECURSIVE, /SMALLER, /LARGER, /AFTER, /BEFORE, /EXCEPT, etc.
  6280. The resulting array has the number of files (n) as its 0th
  6281. element, and the filenames in elements 1 through n Example:
  6282. dir /array:&a /files /nobackup /after:19990101 /larger:10000 [ab]*
  6283. show array &a
  6284. /FILES
  6285. Only show regular files.
  6286. /DIRECTORIES
  6287. Only show directories.
  6288. /BACKUP
  6289. In UNIX, OS-9, K-95, and other versions that support SET FILE
  6290. COLLISION BACKUP and create backup files by appending .~n~ to
  6291. the filename (where "n" is a number), /BACKUP means to include
  6292. these files in directory listings. This is the default.
  6293. /NOBACKUP
  6294. This is the opposite of /BACKUP: that is, do not include backup
  6295. files in the listing.
  6296. /BRIEF
  6297. List filenames only; use a compact format, as many filenames as
  6298. will fit across the screen (based on the longest name). A brief
  6299. listing is always sorted alphabetically.
  6300. /VERBOSE
  6301. List one file per line, and include date, size, and (in UNIX
  6302. only) permissions of each file. This is the opposite of /BRIEF,
  6303. and is the default.
  6304. /PAGE
  6305. Pause at the end of each screenful and give a "more?" prompt,
  6306. even if SET COMMAND MORE-PROMPTING is OFF.
  6307. /NOPAGE
  6308. Don't pause at the end of each screenful and give a "more?"
  6309. prompt, even if SET COMMAND MORE-PROMPTING is ON. If neither
  6310. /PAGE or /NOPAGE is given, paging is according to the prevailing
  6311. COMMAND MORE-PROMPTING setting (which can be displayed with SHOW
  6312. COMMAND).
  6313. /ENGLISHDATE
  6314. Show dates in dd-mmm-yyyy format; mmm is the first three letters
  6315. of the English month name.
  6316. /ISODATE
  6317. Show dates in yyyy-mm-dd format; mm is the month number, 1-12.
  6318. This is the opposite of /ENGLISHDATE, and is the default.
  6319. /HEADINGS
  6320. Print a heading before the listing and a summary at the end.
  6321. /NOHEADINGS
  6322. Don't print a heading before the listing or a summary at the
  6323. end. This is the opposite of /HEADINGS, and is the default.
  6324. /XFERMODE
  6325. Only in Kermit programs that support SET FILE PATTERNS. If this
  6326. switch is included, and the filename matches any FILE
  6327. BINARY-PATTERN ( Section 4.3), "(B)" is printed after the
  6328. filename; otherwise, if it matches a FILE TEXT-PATTERN, "(T)" is
  6329. printed.
  6330. /NOXFERMODE
  6331. Don't display transfer-mode indicators. This is the opposite of
  6332. /XFERMODE and is the default.
  6333. /RECURSIVE
  6334. Show files not only in the given directory, but also in its
  6335. subdirectories (if any), their subdirectories, etc.
  6336. /NORECURSIVE
  6337. Don't show files in subdirectories. This is the opposite of
  6338. /RECURSIVE, and is the default.
  6339. /MESSAGE:text
  6340. This lets you specify a short text string to be appended to the
  6341. end of each directory listing line (a space is supplied
  6342. automatically). If the text contains any spaces, enclose it in
  6343. braces, e.g. /MESSAGE:{two words}.
  6344. /NOMESSAGE
  6345. Don't append any message to the end of each directory listing
  6346. line (default).
  6347. /SORT:[{NAME,SIZE,DATE}]
  6348. Sort the listing by name, size, or date. If the /SORT switch is
  6349. given but the "sort-by" keyword is omitted, the listing is
  6350. sorted by name. /SORT:NAME /ASCENDING (alphabetic sort by name)
  6351. is the default.
  6352. /NOSORT
  6353. Don't sort the listing. Files are listed in whatever order they
  6354. are supplied by the operating system, e.g. inode order in UNIX.
  6355. /REVERSE
  6356. If the /SORT switch is given, reverse the order of the sort.
  6357. Synonym: /DESCENDING.
  6358. /ASCENDING
  6359. If the /SORT switch is given, sort the listing in normal order.
  6360. This is the opposite of /REVERSE and is the default.
  6361. Note that most of the DIRECTORY-specific switches come in pairs, in
  6362. which one member of a pair (e.g. /NOHEADINGS) is the opposite of the
  6363. other (e.g. /HEADINGS).
  6364. If you always want to use certain options, you can set them with the
  6365. SET OPTIONS DIRECTORY command ( Section 1.5.5). Use SHOW OPTIONS to
  6366. list the options currently in effect. To make the desired options apply
  6367. every time you run C-Kermit, put a SET OPTIONS DIRECTORY command in
  6368. your C-Kermit customization file, specifying the desired options.
  6369. Options set in this manner apply to every subsequent DIRECTORY command.
  6370. Of course, if you include switches in a DIRECTORY command, these
  6371. override any defaults, built-in or custom. Example:
  6372. DIRECTORY ; Use "factory defaults"
  6373. SET OPTIONS DIRECTORY /SORT:SIZE /REVERSE /HEADINGS ; Customize defaults
  6374. DIRECTORY ; Use customized defaults
  6375. DIR /SORT:NAME ; Override customized default SORT key
  6376. SET OPT DIR /RECURS ; Add /RECURSIVE to customized defaults
  6377. DIR /ASCEND ; Override customized default SORT order
  6378. Notes:
  6379. * Only a single sort key is supported; there is presently no way to
  6380. have multiple sort keys.
  6381. * If the /BRIEF switch is given, all other switches (except
  6382. /[NO]RECURSIVE, /[NO]DOTFILES, /DIRECTORIES, /FILES, and /ALL) are
  6383. ignored.
  6384. * /SORT:anything gives incorrect results if any files have lengths
  6385. greater than 10 digits (i.e. that are more than 9999999999 bytes
  6386. long, i.e. if they are 10GB or more in size) because the overlong
  6387. length field causes the date and name fields to be misaligned.
  6388. * /SORT:NAME is redundant in VMS since VMS returns filenames in
  6389. alphabetic order anyway.
  6390. * /SORT:NAME ignores alphabetic case on platforms where case does not
  6391. matter in filenames, but this works only for unaccented Roman
  6392. letters A-Z.
  6393. * /SORT:NAME is currently based on code values, and so works fine for
  6394. ASCII, but will probably produce unexpected results for files with
  6395. non-ASCII or 8-bit characters in their names. (Locale-based sorting
  6396. raises rather significant issues of portability, size, performance,
  6397. etc.)
  6398. * /SORT:DATE works right only for ISO-format dates, not English ones.
  6399. * /SORT:SIZE sorts the size field lexically. On some platforms (e.g.
  6400. Windows), the size of a directory file is listed as "<DIR>" rather
  6401. than as a number; in this case, the "<DIR>" files are gathered at
  6402. the end (or beginning, depending on the sort order) of the listing.
  6403. * /RECURSIVE is accepted but ignored in AOS/VS. Use the normal
  6404. system-specific filespec notation, e.g. "dir #.txt".
  6405. * /RECURSIVE has no affect when a full, absolute pathname is given;
  6406. e.g. "dir /recursive /tmp/foo" (where "foo" is a regular file) only
  6407. shows the "/tmp/foo" file. If you want to see all "foo" files in
  6408. the /tmp tree, do "cd /tmp" and then "dir /recursive foo".
  6409. * If a file size of -1 is shown, or date-time of 0000-00-00 00:00:00,
  6410. this means the file was located, but access to information about
  6411. the file was denied to C-Kermit.
  6412. * In VMS, if FOO.DIR;1 is a directory within your current directory,
  6413. "directory foo" and "directory [.foo]" list the files in the [.FOO]
  6414. subdirectory, but "directory foo.dir" lists the directory file
  6415. itself; similarly for "*.dir" versus "[.*]", etc.
  6416. * In UNIX, if "foo" is a directory within your current directory,
  6417. "directory foo" lists the files in the foo directory. If you want
  6418. to list the foo directory file itself, put an asterisk at the end:
  6419. "dir foo*".
  6420. Hint: How to find the biggest files in a directory tree:
  6421. cd xxx ; (root of tree)
  6422. directory /sort:size /recursive /reverse /dotfiles /page
  6423. Another hint: If you often use several different directory-listing
  6424. formats, define macro shortcuts for them:
  6425. DEFINE WD DIRECTORY /SORT:DATE /REVERSE \%* ; Reverse chronological order
  6426. DEFINE SD DIRECTORY /SORT:SIZE /REVERSE \%* ; Reverse order of size
  6427. DEFINE ND DIRECTORY /SORT:NAME /ASCEND \%* ; Alphabetical by name
  6428. DEFINE DL DIR /DIR /SORT:NAME /ASCEND \%* ; Alphabetical directory list
  6429. Put these definitions in your C-Kermit customization file. Note that
  6430. "\%*" ( Section 7.5) in these definitions lets you include other
  6431. switches in your macro invocations, e.g.:
  6432. wd /headings *.txt
  6433. Of course you can still access your external directory listing program
  6434. by using RUN or "!", e.g. in VMS:
  6435. run directory /size/date/protection/except=*.obj oofa.*;0
  6436. or:
  6437. !dir /size/date/prot/exc=*.obj oofa.*;0
  6438. In UNIX, use "!ls" or just "ls" (which is a special synonym for "!ls").
  6439. 4.5.2. The CD and BACK Commands
  6440. In C-Kermit 7.0, the CD command has a new friend, the BACK command.
  6441. BACK means "CD to my previous current directory". A second BACK brings
  6442. you back to where you were before the first one; thus successive BACK
  6443. commands switch back and forth between two directories.
  6444. 4.5.2.1. Parsing Improvements
  6445. The CD command, as well as other commands that parse a directory name,
  6446. were changed in 7.0 to provide all the expected functions: completion
  6447. on Tab or Esc, directory-name lists on ?, etc. Other affected commands
  6448. include SET SERVER GET-PATH, SET TEMP-DIRECTORY, SET FILE
  6449. DOWNLOAD-DIRECTORY, and SPACE. CD and REMOTE CD also now work with
  6450. logical names.
  6451. In VMS, the situation is a bit complicated since a directory name can
  6452. look like "DEV:", "[FOO.BAR]", "DEV:[FOO.BAR]", "[FOO]BAR.DIR;1", etc.
  6453. Completion and ?-help might not always work, but they do in many cases.
  6454. Examples:
  6455. cd ? Lists all subdirectories of the current directory
  6456. cd []? Ditto
  6457. cd k? Ditto, but only those starting with K
  6458. cd [foo]? Lists all subdirectories of the [FOO] directory
  6459. cd [-]? Lists all subdirectories of the superior directory
  6460. cd [--]? Lists all subdirectories of the directory 2 levels up
  6461. cd [...]? Lists all directories below the current one
  6462. cd [foo.? Does not work.
  6463. C-Kermit allows all of the following in VMS:
  6464. cd bar CD to subdirectory BAR of the current directory
  6465. cd .bar Ditto
  6466. cd [.bar] Ditto
  6467. cd bar.dir etc...
  6468. cd bar.dir;
  6469. cd bar.dir;1
  6470. cd [foo.bar]
  6471. cd <foo.bar>
  6472. cd bar.baz This can go more than 1 level deep...
  6473. cd dir: (where logical name DIR is defined as [FOO.BAR])
  6474. As well as the following:
  6475. cd .. Go up one level as in UNIX
  6476. cd . The current directory
  6477. cd My login directory
  6478. Note that "cd -" (go up one level) does not work as expected, because
  6479. "-" is Kermit's command continuation character. However, "cd [-]", and
  6480. "
  6481. cd {-}" have the desired effect (and so does "cd ..", which is easier
  6482. to type).
  6483. 4.5.2.2. The CDPATH
  6484. The CD command in the UNIX, Windows, OS/2, and VMS versions of
  6485. C-Kermit, as of version 6.1 / 1.1.12, searches the CDPATH for the given
  6486. directory, if it is not absolute and if a CDPATH environment variable
  6487. is defined. Example (in UNIX ksh or bash):
  6488. $ export CDPATH=$HOME:$HOME/kermit:/tmp
  6489. Now if you give a "cd xxx" command, no matter what your current
  6490. directory is, if the "xxx" directory is not a subdirectory of your
  6491. current directory, then the xxx subdirectory of your home directory is
  6492. used or if that does not exist, then the xxx subdirectory of the kermit
  6493. subdirectory of your home directory is used or if that does not exist,
  6494. then /tmp/xxx is used. This is how the ksh "cd" command works, and now
  6495. the C-Kermit CD command works the same way.
  6496. In VMS, you can define CDPATH to be a list of directories that contain
  6497. actual directory delimiters, and/or logical names representing
  6498. directories, using commas to separate them, e.g.:
  6499. $ define cdpath [HOME],[SOMEOTHERDIR],[HOME.MISC]
  6500. $ define cdpath SYS$LOGIN:,DISK1:[HOME],DISK2:[SCRATCH.IVAN]
  6501. Example:
  6502. $ define cdpath SYS$LOGIN:,[IVAN],[OLAF],[OLGA.MISC]
  6503. $ kermit
  6504. DISK1:[OLGA] C-Kermit> cd blah
  6505. tries the BLAH subdirectory of the user's login directory, then
  6506. [OLGA.BLAH], [IVAN.BLAH], [OLAF.BLAH], and [OLGA.MISC.BLAH], in that
  6507. order, using the first one it finds, failing if it finds none.
  6508. In C-Kermit 7.0, you may also set the CDPATH from the Kermit prompt:
  6509. SET CD PATH path
  6510. Allows the CD PATH to be set from within C-Kermit.
  6511. SHOW CD shows the CD path and all other information relevant to the CD
  6512. command.
  6513. 4.5.2.3. CD Messages
  6514. Whenever you change directory, you can have C-Kermit display a "Read
  6515. Me" file from the new directory automatically. The commands are:
  6516. SET CD MESSAGE { ON, OFF, FILE list }
  6517. ON enables this feature; OFF (the default) disables it. File
  6518. lets you specify the name of the "Read Me" file. A list of names
  6519. to look for can be given in the following format:
  6520. {{name1}{name2}{name3}{...}}
  6521. e.g.:
  6522. SET SERVER CD-MESSAGE FILE {{./.readme}{README.TXT}{READ.ME}}
  6523. The default list of CD-message files is system dependent.
  6524. SHOW CD shows your current directory, previous directory, CD path, and
  6525. CD message info.
  6526. 4.5.3. Creating and Removing Directories
  6527. The MKDIR command now allows you to create multiple directories at
  6528. once:
  6529. C-Kermit> mkdir a/b/c/d
  6530. creates the directory a in the current directory (if it doesn't exist
  6531. already), and then creates subdirectory b in the a directory (if it
  6532. didn't exist already), and so on.
  6533. If you use MKDIR to try to create a directory that already exists,
  6534. C-Kermit will print a warning ("?Directory already exists"), but the
  6535. MKDIR command will still succeed. If you want to avoid the warning
  6536. message, use IF DIRECTORY first to check if the directory already
  6537. exists.
  6538. The RMDIR command, however, will not remove more than one directory,
  6539. nor will it remove a directory that contains any files. (There is, as
  6540. yet, no RMDIR /RECURSIVE command, although one might be added later.)
  6541. In VMS, these commands (like CD) are more forgiving of your syntax than
  6542. is the DCL command shell; "mkdir oofa" is equivalent to "mkdir [.oofa]"
  6543. and so on. Also in VMS, you'll find that C-Kermit's RMDIR command is
  6544. easier than deleting a directory in DCL, since it automatically first
  6545. gives it owner delete permission if you are the owner.
  6546. 4.5.4. The DELETE and PURGE Commands
  6547. The DELETE command now offers a selection of switches, and has a new
  6548. companion, the PURGE command. First, DELETE:
  6549. DELETE [ switches... ] filespec
  6550. Deletes the file or files that match the filespec, which may
  6551. contain wildcards ( Section 4.9).
  6552. Optional switches include the standard file-selection switches
  6553. presented in Section 1.5.4, plus:
  6554. /ASK
  6555. Before deleting each file, ask permission interactively. Answers
  6556. are Yes or OK (delete the file), No (don't delete it), or Quit
  6557. (stop executing the DELETE command).
  6558. /NOASK
  6559. Don't ask permission to delete each file.
  6560. /LIST
  6561. List each file and show whether it was deleted. Synonyms: /LOG,
  6562. /VERBOSE.
  6563. /NOLIST
  6564. Don't list files while deleting them. Synonyms: /NOLOG, /QUIET.
  6565. /HEADING
  6566. Print a heading and summary line.
  6567. /NOHEADING
  6568. Don't print a heading and summary line.
  6569. /PAGE
  6570. When listing, pause at the end of each screenful and give the
  6571. "More?" prompt. If you reply "n" (no), the DELETE command
  6572. terminates.
  6573. /SIMULATE
  6574. Do everything implied by the given switches and filespec, except
  6575. do not actually delete any files. This lets you preview which
  6576. files would be deleted; implies /LIST.
  6577. Now the PURGE command:
  6578. PURGE [ switches... ] [ filespec ]
  6579. (VMS only) Runs the DCL PURGE command. Switches and filespec, if
  6580. any, are passed directly to DCL without parsing or verification.
  6581. Deletes excess versions of the given (or all) files. The rest of
  6582. this section does not apply to VMS.
  6583. PURGE [ switches... ] [ filespec ]
  6584. (UNIX only) Deletes "backup files" that match the filespec,
  6585. which may contain wildcards ( Section 4.9). If no filespec
  6586. is given, all backup files in the current directory are selected
  6587. (subject to modification by any switches). Do not include backup
  6588. notation in the filespec.
  6589. Explanation:
  6590. To avoid destroying preexisting files when a new file arrives that has
  6591. the same name, C-Kermit backs up the old file by appending a "backup
  6592. number" to its name. In UNIX, the backup suffix consists of a period, a
  6593. tilde, a number, and another tilde. For example, if a file called
  6594. oofa.txt exists and a new oofa.txt file arrives, the original is
  6595. renamed to oofa.txt.~1~. If another oofa.txt file arrives, the existing
  6596. one is renamed to oofa.txt.~2~. And so on. This system is compatible
  6597. with the one used by EMACS. Thus over time, if you receive a lot of
  6598. files with C-Kermit or edit them with EMACS, backup files can build up.
  6599. The new PURGE command lets you clean out accumulated backup files:
  6600. Optional switches include the standard file-selection switches
  6601. presented in Section 1.5.4, plus all the switches listed above for
  6602. the DELETE command, plus:
  6603. /KEEP:n
  6604. Retains the n most recent (highest-numbered) backup files for
  6605. each file. For example, if oofa.txt, oofa.txt.~1~, oofa.txt.~2~,
  6606. oofa.txt.~10~, oofa.txt.~12~, and oofa.txt.~100~ exist, "purge
  6607. /keep:2 oofa.txt" deletes oofa.txt.~1~, oofa.txt.~2~, and
  6608. oofa.txt.~10~, and keeps oofa.txt, oofa.txt.~12~, and
  6609. oofa.txt.~100~. If /KEEP is given without a number, one (the
  6610. highest numbered) backup file is kept.
  6611. CAUTION: The PURGE command should be used only when *.~*~ files truly
  6612. are backup files. This is the case for EMACS, and it is the DEFAULT for
  6613. C-Kermit. However, if C-Kermit's FILE COLLISION has been set to RENAME,
  6614. newly received files will look like backup files. In that case, don't
  6615. use the PURGE command or you'll be removing new files rather than old
  6616. ones. (Use SHOW FILE to find the FILE COLLISION setting.)
  6617. The PURGE command is presently available only in UNIX. The command
  6618. succeeds if it deleted any files, or if it deleted no files but there
  6619. were no errors. It fails if it deleted no files and there were errors
  6620. (i.e. deletion was attempted but failed). In VMS, backup file versions
  6621. are handled automatically by the OS, and a PURGE command can be used at
  6622. the VMS prompt to clean them up.
  6623. If you want certain switches to be supplied automatically with each
  6624. DELETE or PURGE command, you can set them with SET OPTIONS
  6625. ( Section 1.5.5) and you can display any such settings with SHOW
  6626. OPTIONS. Of course you can override them on a per-command basis by
  6627. including switches in your PURGE or DELETE command.
  6628. Also see SET FILE COLLISION, SHOW FILE, SEND /NOBACKUP, SET SEND
  6629. BACKUP, and DIRECTORY /[NO]BACKUP.
  6630. 4.6. Starting the Remote Kermit Server Automatically
  6631. As noted on pages 275-276 ofUsing C-Kermit 2nd edition, you can
  6632. have Kermit send "kermit receive" commands automatically when it is in
  6633. local mode and you give a SEND or similar command, to start the remote
  6634. Kermit receiver in case it is not already started. The "kermit receive"
  6635. commands are specified by:
  6636. SET PROTOCOL KERMIT binary-receive-command text-receive-command
  6637. As of version 7.0, a Kermit protocol option has been added to send a
  6638. string to the host in advance of any Kermit packets when you give a
  6639. GET-class or REMOTE command. This will switch the remote C-Kermit into
  6640. the appropriate mode or, if the remote system is at a system command
  6641. (shell) prompt, execute the string on the remote system. The new syntax
  6642. of the SET PROTOCOL KERMIT command is:
  6643. SET PROTOCOL KERMIT [ s1 [ s2 [ s3 ] ] ]
  6644. where:
  6645. Default Meaning
  6646. s1 {kermit -ir} Remote "kermit receive in binary mode" command.
  6647. s2 {kermit -r} Remote "kermit receive in text mode" command.
  6648. s3 {kermit -x} Remote "start kermit server" command.
  6649. NOTE: If the remote Kermit is 6.0, the following are recommended for
  6650. fast startup and high-performance file transfer (see Appendix I in
  6651. Using C-Kermit, second Edition, for command-line options):
  6652. s1 kermit -YQir (Kermit receive binary, skip init file, fast.)
  6653. s2 kermit -YQTr (Kermit receive text, skip init file, fast.)
  6654. s3 kermit -YQx (Kermit server, skip init file, fast.)
  6655. If the remote is C-Kermit 7.0 or later, change the -x option (enter
  6656. server mode) to -O (uppercase letter O), which means "enter server mode
  6657. for One transaction only); this way, it is not stuck in server after
  6658. the transfer. Also note that the Q is redundant in version 7.0, since
  6659. fast Kermit protocol settings are now the default.
  6660. Note that in case the C-Kermit executable is called "wermit" or
  6661. "ckermit" you can change "kermit" in the strings above to "wermit" or
  6662. "ckermit" and C-Kermit 7.0 or later will recognize these as synonyms
  6663. for "kermit", in case it is at its command prompt when one of these
  6664. strings is sent to it.
  6665. 4.7. File-Transfer Command Switches
  6666. Over the years, various new methods of transferring a file have
  6667. accumulated, until we had, in addition to the SEND command, also MOVE
  6668. (send and then delete), MAIL (send as email), REMOTE PRINT (send to be
  6669. printed), CSEND (send the output of a command), PSEND (send a part of a
  6670. file), BSEND (send in binary mode), RESEND (resume an interrupted
  6671. SEND), etc etc. Similarly: GET, REGET, CGET, RETRIEVE, and so on.
  6672. Not only is it confusing to have different names for these commands,
  6673. many of which are not real words, but this also does not allow all
  6674. combinations, like "send a file as mail, then delete it".
  6675. In C-Kermit 7.0, the SEND, GET, and RECEIVE commands were restructured
  6676. to accept modifier switches (switches are explained inSection
  6677. 1.5).
  6678. 4.7.1. SEND Command Switches
  6679. Without switches, the SEND command still works exactly as before:
  6680. send oofa.txt ; send a single file
  6681. send oofa.* ; send multiple files
  6682. send oofa.txt x.x ; send oofa.txt as x.x (tell receiver its name is x.x)
  6683. send ; send from SEND-LIST
  6684. But now the following modifier switches may be included between "send"
  6685. and the filename. Zero, one, two, or more switches may be included in
  6686. any combination that makes sense. Switch names (such as /BINARY) can be
  6687. abbreviated, just like any other keywords. Most of these switches work
  6688. only when using Kermit protocol (/TEXT and /BINARY are the exceptions).
  6689. /AFTER:date-time
  6690. Specifies that only those files modified (or, in VMS, created)
  6691. after the given date-time (see Section 1.6) are to be sent.
  6692. Examples:
  6693. send /text /after:{2-Feb-1997 10:28:30} *.txt
  6694. send /text /after:\fdate(oofa.txt) *.txt
  6695. Synonym: /SINCE.
  6696. /ARRAY:arrayname
  6697. Specifies that instead of sending a file, C-Kermit is to send
  6698. the contents of the given array. Since an array does not have a
  6699. filename, you should include an /AS-NAME switch to specify the
  6700. name under which the array is to be sent (if you do not, the
  6701. name "_array_x_" is used, where 'x' is replaced by the array
  6702. designator). Seesection 7.10 for array-name syntax. As
  6703. noted in that section, you can also include a range to have a
  6704. segment of the array sent, rather than the whole thing; for
  6705. example: "send /array:&a[100:199]". It is strongly recommended
  6706. that you accompany the /ARRAY switch with a /TEXT or /BINARY
  6707. switch to force the desired transfer mode, since otherwise the
  6708. various automatic mechanisms might switch to binary mode when
  6709. you really wanted text, or vice versa. In text mode a line
  6710. terminator is added to the end of each array element, but not in
  6711. binary mode. For details and examples see Section 7.10.11.
  6712. /AS-NAME:text
  6713. Specifies "text" as the name to send the file under. You can
  6714. also still specify the as-name as the second filename on the
  6715. SEND command line. The following two commands are equivalent:
  6716. send oofa.txt oofa.new
  6717. send /as:oofa.new oofa.txt
  6718. /BEFORE:date-time
  6719. Specifies that only those files modified (or, in VMS, created)
  6720. before the given date-time ( Section 1.6) are to be sent.
  6721. /BINARY
  6722. Performs this transfer in binary mode without affecting the
  6723. global transfer mode, overriding not only the FILE TYPE and
  6724. TRANSFER MODE settings, but also the FILE PATTERN setting, but
  6725. for this SEND command only. In other words, SEND /BINARY means
  6726. what it says: send the file in binary mode, regardless of any
  6727. other settings. Example:
  6728. set file type text ; Set global transfer mode to text
  6729. send /binary oofa.zip ; Send a file in binary
  6730. send oofa.txt ; This one is sent in text mode
  6731. /COMMAND
  6732. SEND /COMMAND is equivalent to CSEND ( Section 4.2.2) -- it
  6733. says to send the output from a command, rather than the contents
  6734. of a file. The first "filename" on the SEND command line is
  6735. interpreted as the name of a command; the second (if any) is the
  6736. as-name. Examples:
  6737. send /command {grep Sunday oofa.txt} sunday.txt
  6738. send /as-name:sunday.txt /command {grep Sunday oofa.txt}
  6739. send /bin /command {tar cf - . | gzip -c} {!gunzip -c | tar xf -}
  6740. /DELETE
  6741. Deletes the file (or each file in the group) after it has been
  6742. sent successfully (but does not delete it if it was not sent
  6743. successfully). SEND /DELETE is equivalent to MOVE. Has no effect
  6744. when used with /COMMAND. Example:
  6745. send /delete *.log
  6746. /DOTFILES
  6747. (UNIX and OS-9 only) Normally files whose names begin with "."
  6748. are skipped when matching wildcards that do not also begin with
  6749. ".". Include /DOTFILES to force these files to be included too.
  6750. /RECURSIVE
  6751. Descend the through the directory tree when locating files to
  6752. send. Automatically sets /PATHNAMES:RELATIVE. Explained in
  6753. Section 4.11 .
  6754. /EXCEPT:pattern
  6755. See Section 1.5.4.
  6756. /NOBACKUP
  6757. This means to skip backup files when sending, even if they match
  6758. the SEND file specification. This is equivalent to using SEND
  6759. /EXCEPT and including *.~[0-9]*~ in the exception list (or *.~*~
  6760. if Kermit was built without pattern-matching support; see
  6761. Section 4.9.1). Including this switch is equivalent to
  6762. giving SET SEND BACKUP OFF ( Section 4.0.6) prior to SEND,
  6763. except its effect is local to the SEND command with which it was
  6764. given.
  6765. /NODOTFILES
  6766. The opposite of /DOTFILES (q.v.)
  6767. /FILENAMES:{CONVERTED,LITERAL}
  6768. Use this switch to override the current global SET FILE NAMES
  6769. setting for this transfer only.
  6770. /FILTER:command
  6771. This specifies a filter to pass the file through before sending
  6772. it. See thesection on file-transfer pipes and filters. The
  6773. /FILTER switch applies only to the file-transfer command it is
  6774. given with; it does not affect the global SEND FILTER setting,
  6775. if any.
  6776. /IMAGE
  6777. VMS: Sends in image mode. Non-VMS: same as /BINARY.
  6778. /LABELED
  6779. VMS and OS/2 only: Sends in labeled mode.
  6780. /LARGER-THAN:number
  6781. Specifies that only those files that are longer than the given
  6782. number of bytes are to be sent.
  6783. /LISTFILE:filename
  6784. Specifies that the files to be sent are listed in a file with
  6785. the given filename. The file contains one filename per line.
  6786. These filenames are not checked in any way; each filename is
  6787. taken and does not use or depend on any Kermit-specific syntax.
  6788. In particular, backslashes are not treated specially, leading
  6789. and trailing spaces are not stripped, etc. However, if a
  6790. filename contains wildcards, they are expanded. Example: If a
  6791. file named files.txt contains the following lines:
  6792. blah.txt
  6793. oofa*
  6794. x.x
  6795. (but without leading or trailing spaces), then the C-Kermit
  6796. command "send /listfile:files.txt" will send the files blah.txt,
  6797. x.x, and all files whose names start with "oofa", assuming the
  6798. files exist and are readable. The /LISTFILE switch, can, of
  6799. course, be used with other switches when it makes sense, for
  6800. example, /EXCEPT, /BINARY, /AFTER, /SMALLER, /MOVE-TO, /DELETE,
  6801. /AS-NAME with a template, etc.
  6802. /MAIL:address
  6803. Sends the file as e-mail to the given address or addresses.
  6804. "send /mail:address filename" is equivalent to "mail filename
  6805. address". You can include multiple addresses separated by
  6806. commas. Examples:
  6807. send /mail:kermit-support@columbia.edu packet.log
  6808. send /mail:cmg,fdc,jrd oofa.txt
  6809. As with any switch argument, if the address or address list
  6810. contains any spaces, you must enclose it in braces. The format
  6811. of the addresses must agree with that understood by the
  6812. mail-sending program on the receiver's computer.
  6813. /MOVE-TO:directory-name
  6814. Specifies that after each (or the only) source file is sent
  6815. successfully, and ONLY if it is sent successfully, it should be
  6816. moved to the named directory. If the directory name contains
  6817. spaces, enclose it in braces. If the directory does not exist,
  6818. it is created if possible; if it can't be created, the command
  6819. fails and an error message is printed. Example:
  6820. send /text /move-to:/users/olga/backup/ *.txt
  6821. /NOT-AFTER:date-time
  6822. Specifies that only those files modified at or before the given
  6823. date and time are to be sent.
  6824. /NOT-BEFORE:date-time
  6825. Specifies that only those files modified at or after the given
  6826. date and time are to be sent.
  6827. /PATHNAMES:{OFF,ABSOLUTE,RELATIVE}
  6828. Use this switch to override the current global SET SEND
  6829. PATHNAMES setting for this transfer only. /PATHNAMES:ABSOLUTE or
  6830. RELATIVE also sets /FILENAMES:LITERAL (also for this transfer
  6831. only) since pathnames are not sent otherwise.
  6832. /RENAME-TO:text
  6833. Specifies that after the (or each) source file is sent
  6834. successfully, and ONLY if it is sent successfully, it should be
  6835. renamed to the name given. If the name contains spaces, enclose
  6836. it in braces. If a file group is being sent, then the "text"
  6837. must contain a variable reference such as \v(filename) (see
  6838. Section 4.1). Example:
  6839. send /rename-to:ok_\v(filename) *.*
  6840. This sends each file in the current directory and if it was sent
  6841. successfully, changes its name to begin with "ok_".
  6842. /SMALLER-THAN:number
  6843. Specifies that only those files that are smaller than the given
  6844. number of bytes are to be sent.
  6845. /SUBJECT:text
  6846. Subject for email. Actually, this is just a synonym for
  6847. /AS-NAME. If the text includes spaces, you must enclose it in
  6848. braces. If you don't specify a subject (or as-name), the name of
  6849. the file is used as the subject. Example:
  6850. send /mail:kermit-support@columbia.edu /subj:{As requested} packet.log
  6851. /PRINT:options
  6852. Sends the file to be printed, optionally specifying options for
  6853. the printer. Equivalent to REMOTE PRINT filename options.
  6854. Examples:
  6855. send /print oofa.txt ; No options.
  6856. send /print:/copies=3 oofa.txt ; "/copies=3" is a VMS PRINT switch.
  6857. send /print:-#3 oofa.txt ; "-#3" is a UNIX lpr switch.
  6858. /PROTOCOL:name
  6859. Uses the given protocol to send the file (Kermit, Zmodem, etc)
  6860. for this transfer without changing global protocol. Only
  6861. available in Kermit 95, UNIX, and OS-9. Example:
  6862. set protocol kermit ; Set global protocol
  6863. send /proto:zmodem /bin oofa.zip ; Send just this file with Zmodem
  6864. send oofa.txt ; This file is sent with Kermit
  6865. /QUIET
  6866. When sending in local mode, this suppresses the file-transfer
  6867. display.
  6868. /RECOVER
  6869. Used to recover from a previously interrupted transfer; SEND
  6870. /RECOVER is equivalent to RESEND. Recovery only works in binary
  6871. mode; SEND /RECOVER and RESEND include an implied /BINARY
  6872. switch. Even then, recovery will successful only if (a) the
  6873. original (interrupted) transfer was also in binary mode, or (b)
  6874. if it was in text mode, the two Kermit programs run on platforms
  6875. where text-mode transfers are not length-changing.
  6876. /STARTING:number
  6877. Starts sending the file from the given byte position. SEND
  6878. /STARTING:n filename is equivalent to PSEND filename n.
  6879. /TEXT
  6880. Performs this transfer in text mode without affecting the global
  6881. transfer mode, overriding not only the FILE TYPE and TRANSFER
  6882. MODE settings, but also the FILE PATTERN setting, for this SEND
  6883. command only. In other words, SEND /TEXT really send the file in
  6884. text mode, regardless of any other settings or negotiations.
  6885. About mail... Refer to Section 4.7.1. The same rules apply as for
  6886. file transfer. If you are mailing multiple files, you can't use an
  6887. as-name (in this case, a subject) unless it contains replacement
  6888. variables like \v(filenum). For example, if you:
  6889. send /mail:somebody@xyz.com *.txt
  6890. Then each file will arrive as a separate email message with its name as
  6891. the subject. But if you:
  6892. send /mail:somebody@xyz.com /subject:{Here is a file} *.txt
  6893. Then each file message will have the same subject, which is probably
  6894. not what you want. You can get around this with constructions like:
  6895. send /mail:somebody@xyz.com /subject:{Here is \v(filename)} *.txt
  6896. which embed the filename in the subject.
  6897. The MOVE, CSEND, MAIL, and RESEND commands now also accept the same
  6898. switches. And the switches are also operative when sending from a
  6899. SEND-LIST (seeUsing C-Kermit, 2nd Ed, pp.191-192), so, for
  6900. example, it is now possible to SEND /PRINT or SEND /MAIL from a
  6901. SEND-LIST.
  6902. The MSEND and MMOVE commands also take switches, but not all of them.
  6903. With these commands, which take an arbitrary list of filespecs, you can
  6904. use /BINARY, /DELETE, /MAIL, /PRINT, /PROTOCOL, /QUIET, /RECOVER, and
  6905. /TEXT (and /IMAGE or /LABELED, depending on the platform). MMOVE is
  6906. equivalent to MSEND /DELETE. (If you want to send a group of files, but
  6907. in mixed transfer modes with per-file as-names, use ADD SEND-LIST and
  6908. then SEND.)
  6909. The MSEND/MMOVE switches come before the filenames, and apply to all of
  6910. them:
  6911. msend /print /text *.log oofa.txt /etc/motd
  6912. If you type any of these commands (SEND, CSEND, MSEND, etc) followed by
  6913. a question mark (?), you will see a list of the switches you can use.
  6914. If you want to see a list of filenames, you'll need to type something
  6915. like "send ./?" (UNIX, OS/2, Windows, etc), or "send []?" (VMS), etc.
  6916. Of course, you can also type pieces of a filename (anything that does
  6917. not start with "/") and then "?" to get a list of filenames that start
  6918. that way; e.g. "send x.?" still works as before.
  6919. In UNIX, where "/" is also the directory separator, there is usually no
  6920. ambiguity between a fully-specified pathname and a switch, except when
  6921. a file in the root directory has the same name as a switch (as noted in
  6922. Section 1.5):
  6923. send /etc/motd ; Works as expected
  6924. send /command ; ???
  6925. The second example interprets "/command" as a switch, not a filename.
  6926. To send a file actually called "command" in the root directory, use:
  6927. send {/command}
  6928. or other system-dependent forms such as //command, /./command,
  6929. c:/command, etc, or cd to / and then "send command".
  6930. 4.7.2. GET Command Switches
  6931. Without switches, the GET command still works about the same as before:
  6932. get oofa.txt ; GET a single file
  6933. get oofa.* ; GET multiple files
  6934. However, the mechanism for including an "as-name" has changed.
  6935. Previously, in order to include an as-name, you were required to use
  6936. the "multiline" form of GET:
  6937. get
  6938. remote-filespec
  6939. local-name
  6940. This was because the remote filespec might contain spaces, and so there
  6941. would be no good way of telling where it ended and where the local name
  6942. began, e.g:
  6943. get profile exec a foo
  6944. But now since we can use {braces} for grouping, we don't need the
  6945. multiline GET form any more, and in fact, support for it has been
  6946. removed. If you give a GET command by itself on a line, it fails and an
  6947. error message is printed. The new form is:
  6948. GET [ switches... ] remote-name [ local-name ]
  6949. Ask the server to send the file whose name is remote-name. If
  6950. the optional local-name is given, store it locally under this
  6951. name. If the remote-name or local-name contains spaces, they
  6952. must be enclosed in braces:
  6953. get {profile exec a} foo
  6954. get oofa.txt {~/My Files/Oofa text}
  6955. If you want to give a list of remote file specifications, use the MGET
  6956. command:
  6957. MGET [ switches... ] remote-name [ remote-name [ remote-name ... ] ]
  6958. Ask the server to send the files whose names are given.
  6959. Now you can also include modifier switches between GET or MGET and the
  6960. remote-name; most of the same switches as SEND:
  6961. /AS-NAME:text
  6962. Specifies "text" as the name to store the incoming file under.
  6963. (This switch is not available for MGET.) You can also still
  6964. specify the as-name as the second filename on the GET command
  6965. line. The following two commands are equivalent:
  6966. get oofa.txt oofa.new
  6967. get /as:oofa.new oofa.txt
  6968. /BINARY
  6969. Tells the server to send the given file(s) in binary mode
  6970. without affecting the global transfer mode. Example:
  6971. set file type text ; Set global transfer mode to text
  6972. get /binary oofa.zip ; get a file in binary mode
  6973. get oofa.txt ; This one is transferred in text mode
  6974. Or, perhaps more to the point:
  6975. get /binary foo.txt ; where "*.txt" is a text-pattern
  6976. This has the expected effect only if the server is C-Kermit 7.0
  6977. or later or K95 1.1.19 or later.
  6978. /COMMAND
  6979. GET /COMMAND is equivalent to CGET ( Section 4.2.2) -- it
  6980. says to receive the file into the standard input of a command,
  6981. rather than saving it on disk. The /AS-NAME or the second
  6982. "filename" on the GET command line is interpreted as the name of
  6983. a command. Examples:
  6984. get /command sunday.txt {grep Sunday oofa.txt}
  6985. get /command /as-name:{grep Sunday oofa.txt} sunday.txt
  6986. get /bin /command {!gunzip -c | tar xf -} {tar cf - . | gzip -c}
  6987. /DELETE
  6988. Asks the Kermit server to delete the file (or each file in the
  6989. group) after it has been transferred successfully (but not to
  6990. delete it if it was not sent successfully). GET /DELETE is
  6991. equivalent to RETRIEVE. Example:
  6992. get /delete *.log
  6993. /EXCEPT:pattern
  6994. Specifies that any files whose names match the pattern, which
  6995. can be a regular filename, or may contain "*" and/or "?"
  6996. metacharacters, are to be refused upon arrival. To specify
  6997. multiple patterns (up to 8), use outer braces around the group,
  6998. and inner braces around each pattern:
  6999. /EXCEPT:{{pattern1}{pattern2}...}
  7000. See the description of SEND /EXCEPT in Section 4.7.1 for
  7001. examples, etc. Refusal is accomplished using the Attribute
  7002. Rejection mechanism (reason "name"), which works only when
  7003. Attribute packets have been successfully negotiated.
  7004. /FILENAMES:{CONVERTED,LITERAL}
  7005. Use this switch to override the current global SET FILE NAMES
  7006. setting for this transfer only.
  7007. /FILTER:command
  7008. This specifies a filter to pass the incoming file through before
  7009. writing to disk. See thesection on file-transfer pipes and
  7010. filters. The /FILTER switch applies only to the file-transfer
  7011. command it is given with; it does not affect the global RECEIVE
  7012. FILTER setting, if any.
  7013. /IMAGE
  7014. VMS: Transfer in image mode. Non-VMS: same as /BINARY.
  7015. /LABELED
  7016. VMS and OS/2 only: Specifies labeled transfer mode.
  7017. /MOVE-TO:directory
  7018. This tells C-Kermit to move each file that is successfully
  7019. received to the given directory. Files that are not successfully
  7020. received are not moved. By default, files are not moved.
  7021. /PATHNAMES:{OFF,ABSOLUTE,RELATIVE,AUTO}
  7022. Use this switch to override the current global SET RECEIVE
  7023. PATHNAMES setting for this transfer only. /PATHNAMES:ABSOLUTE or
  7024. RELATIVE also sets /FILENAMES:LITERAL (also for this transfer
  7025. only) since incoming pathnames would not be treated as pathnames
  7026. otherwise. See Section 4.10.
  7027. /QUIET
  7028. When sending in local mode, this suppresses the file-transfer
  7029. display.
  7030. /RECOVER
  7031. Used to recover from a previously interrupted transfer; GET
  7032. /RECOVER is equivalent to REGET. Recovery only works in binary
  7033. mode; SEND /RECOVER and RESEND include an implied /BINARY
  7034. switch. Even then, recovery will successful only if (a) the
  7035. original (interrupted) transfer was also in binary mode, or (b)
  7036. if it was in text mode, the two Kermit programs run on platforms
  7037. where text-mode transfers are not length-changing.
  7038. /RECURSIVE
  7039. Tells the server that the GET file specification applies
  7040. recursively. This switch also automatically sets
  7041. /PATHNAMES:RELATIVE in both the server AND the client. When used
  7042. in conjunction with /DELETE, this "moves" a directory tree from
  7043. the server's computer to the client's computer (except that only
  7044. regular files are deleted from the server's computer, not
  7045. directories; thus the original directories will be left, but
  7046. will contain no files). Note that all servers that support
  7047. /RECURSIVE do not necessarily do so in combination with other
  7048. switches, such as /RECOVER. (Servers that do include C-Kermit
  7049. 7.0 and later, K95 1.1.19 and later.)
  7050. /RENAME-TO:string
  7051. This tells C-Kermit to rename each file that is successfully
  7052. received to the given string. Files that are not successfully
  7053. received are not renamed. By default, files are not renamed. The
  7054. string can be a literal string, which is appropriate when only
  7055. one file is being received, or it can contain one or more
  7056. variables that are to be evaluated at the time each file is
  7057. received, such as \v(filename), \v(filenumber), \v(ntime),
  7058. \v(pid), \v(user), etc. WARNING: if you give a literal string
  7059. and more than one file arrives, each incoming file will be given
  7060. the same name (but SET FILE COLLISION BACKUP or RENAME can be
  7061. used to keep the incoming files from overwriting each other).
  7062. /TEXT
  7063. Tells the server to perform this transfer in text mode without
  7064. affecting its global transfer mode. See /BINARY for additional
  7065. info.
  7066. The /MAIL and /PRINT options are not available (as they are for SEND),
  7067. but you can use /COMMAND to achieve the same effect, as in these UNIX
  7068. examples:
  7069. get /command oofa.txt {mail kermit@columbia.edu}
  7070. get /command oofa.txt lpr
  7071. In OS/2 or Windows, you can GET and print like this:
  7072. get oofa.txt prn
  7073. The CGET, REGET, RETRIEVE commands also accept the same switches as
  7074. GET. CGET automatically sets /COMMAND; REGET automatically sets
  7075. /RECOVER and /BINARY, and RETRIEVE automatically sets /DELETE.
  7076. 4.7.3. RECEIVE Command Switches
  7077. Without switches, the RECEIVE command still works as before:
  7078. receive ; Receives files under their own names
  7079. receive /tmp ; Ditto, but into the /tmp directory
  7080. r ; Same as "receive"
  7081. receive foo.txt ; Receives a file and renames to foo.txt
  7082. Now you can also include modifier switches may be included between
  7083. "receive" and the as-name; most of the same switches as GET:
  7084. /AS-NAME:text
  7085. Specifies "text" as the name to store the incoming file under.
  7086. You can also still specify the as-name as a filename on the
  7087. command line. The following two commands are equivalent:
  7088. r oofa.new
  7089. r /as:oofa.new
  7090. /BINARY
  7091. Performs this transfer in binary mode without affecting the
  7092. global transfer mode. NOTE: This does not override the incoming
  7093. filetype (as it does with GET), so this switch is useful only if
  7094. ATTRIBUTE TYPE is OFF, or if the other Kermit does not send a
  7095. TYPE (text or binary) attribute. In any case, it has no affect
  7096. whatsoever on the file sender.
  7097. /COMMAND
  7098. RECEIVE /COMMAND is equivalent to CRECEIVE ( Section 4.2.2)
  7099. -- it says to receive the file into the standard input of a
  7100. command, rather than saving it on disk. The /AS-NAME or the
  7101. "filename" on the RECEIVE command line is interpreted as the
  7102. name of a command.
  7103. r /command {grep Sunday oofa.txt}
  7104. r /command /as-name:{grep Sunday oofa.txt}
  7105. r /bin /command {tar cf - . | gzip -c}
  7106. /EXCEPT:pattern
  7107. Specifies that any files whose names match the pattern, which
  7108. can be a regular filename, or may contain "*" and/or "?"
  7109. metacharacters, are to be refused upon arrival. To specify
  7110. multiple patterns (up to 8), use outer braces around the group,
  7111. and inner braces around each pattern:
  7112. /EXCEPT:{{pattern1}{pattern2}...}
  7113. See the description of SEND /EXCEPT in Section 4.7.1 for
  7114. examples, etc. Refusal is accomplished using the Attribute
  7115. Rejection mechanism (reason "name"), which works only when
  7116. Attribute packets have been successfully negotiated.
  7117. /FILENAMES:{CONVERTED,LITERAL}
  7118. Use this switch to override the current global SET FILE NAMES
  7119. setting for this transfer only.
  7120. /FILTER:command
  7121. This specifies a filter to pass the incoming file through before
  7122. writing to disk. See thesection on file-transfer pipes and
  7123. filters. The /FILTER switch applies only to the file-transfer
  7124. command it is given with; it does not affect the global RECEIVE
  7125. FILTER setting, if any.
  7126. /IMAGE
  7127. VMS: Transfer in image mode. Non-VMS: same as /BINARY. See
  7128. comments under RECEIVE /BINARY.
  7129. /LABELED
  7130. VMS and OS/2 only: Specifies labeled transfer mode. See comments
  7131. under RECEIVE /BINARY.
  7132. /MOVE-TO:directory
  7133. This tells C-Kermit to move each file that is successfully
  7134. received to the given directory. Files that are not successfully
  7135. received are not moved. By default, files are not moved.
  7136. /PATHNAMES:{ABSOLUTE,RELATIVE,OFF,AUTO}
  7137. Use this switch to override the current global SET RECEIVE
  7138. PATHNAMES setting for this transfer only. See Section 4.10.
  7139. /RECURSIVE
  7140. When used with the RECEIVE command, /RECURSIVE is simply a
  7141. synonym for /PATHNAMES:RELATIVE.
  7142. /RENAME-TO:string
  7143. This tells C-Kermit to rename each file that is successfully
  7144. received to the given string. Files that are not successfully
  7145. received are not renamed. By default, files are not renamed. The
  7146. string can be a literal string, which is appropriate when only
  7147. one file is being received, or it can contain one or more
  7148. variables that are to be evaluated at the time each file is
  7149. received, such as \v(filename), \v(filenumber), \v(ntime),
  7150. \v(pid), \v(user), etc. WARNING: if you give a literal string
  7151. and more than one file arrives, each incoming file will be given
  7152. the same name (but SET FILE COLLISION BACKUP or RENAME can be
  7153. used to keep the incoming files from overwriting each other).
  7154. /QUIET
  7155. When receiving in local mode, this suppresses the file-transfer
  7156. display.
  7157. /TEXT
  7158. Receives in text mode without affecting the global transfer
  7159. mode. See comments under RECEIVE /BINARY.
  7160. The /MAIL and /PRINT options are not available, but you can use
  7161. /COMMAND to achieve the same effect, as in these UNIX examples:
  7162. r /command {mail kermit@columbia.edu}
  7163. r /command lpr
  7164. In OS/2 or Windows, you can RECEIVE and print like this:
  7165. receive prn
  7166. The CRECEIVE command now also accepts the same switches.
  7167. 4.8. Minor Kermit Protocol Improvements
  7168. 4.8.1. Multiple Attribute Packets
  7169. C-Kermit 7.0 now sends more than one Attribute packet if a file's
  7170. attributes do not fit into a single packet of the negotiated length. If
  7171. a particular attribute (such as file creation date-time) does not fit
  7172. within the negotiated length (which will only happen when the
  7173. negotiated length is around 20 or less), that attribute is not sent at
  7174. all.
  7175. 4.8.2. Very Short Packets
  7176. There are certain situations where extremely short packets must be
  7177. used; 20 or 30 bytes at most. This can happen when one or more devices
  7178. along the communication path have very small buffers and lack an
  7179. effective means of flow control. Examples are sometimes cited involving
  7180. radio modems.
  7181. When the maximum packet length is shorter than certain packets that
  7182. would be sent, those packets are either truncated or else broken up
  7183. into multiple packets. Specifically:
  7184. 1. Parameter negotiation packets (I, S, and their ACKs) are truncated
  7185. to the negotiated length. Any parameters that do not fit are reset
  7186. to their default values. There is no provision in the Kermit
  7187. protocol for fragmentation and reassembly of parameter strings.
  7188. 2. File header packets (containing the filename) are simply truncated.
  7189. There is no provision in the Kermit protocol for fragmentation and
  7190. reassembly of filenames.
  7191. 3. Attribute packets are fragmented and reassembled as described in
  7192. 4.8.1 without loss of data, except in case a field will not fit at
  7193. all in the negotiated length (the longest attribute is usually the
  7194. date and time of file creation/modification) because of the rule
  7195. that attributes may not be broken across packets.
  7196. 4. Data packets and other packets are unaffected -- they can be as
  7197. short as they need to be, within reason.
  7198. 4.9. Wildcard / File Group Expansion
  7199. "Wildcard" refers to the notation used in filenames to specify a group
  7200. of files by pattern matching.
  7201. 4.9.1. In UNIX C-Kermit
  7202. Prior to C-Kermit 7.0, C-Kermit was capable of expanding wildcard
  7203. strings containing only the "metacharacters" '*' and '?':
  7204. *
  7205. Matches any sequence of zero or more characters. For example:
  7206. "ck*.c" matches all files whose names start with "ck" and end
  7207. with ".c", including "ck.c".
  7208. ?
  7209. Matches any single character. For example, "ck?.c" matches all
  7210. files whose names are exactly 5 characters long and start with
  7211. "ck" and end with ".c". When typing commands at the prompt, you
  7212. must precede any question mark to be used for matching by a
  7213. backslash (\) to override the normal function of question mark,
  7214. which is providing menus and file lists.
  7215. C-Kermit 7.0 adds the additional features that users of ksh, csh, and
  7216. bash are accustomed to:
  7217. [abc]
  7218. Square brackets enclosing a list of characters matches any
  7219. single character in the list. Example: ckuusr.[ch] matches
  7220. ckuusr.c and ckuusr.h.
  7221. [a-z]
  7222. Square brackets enclosing a range of characters; the hyphen
  7223. separates the low and high elements of the range. For example,
  7224. [a-z] matches any character from a to z.
  7225. [acdm-z]
  7226. Lists and ranges may be combined. This example matches a, c, d,
  7227. or m through z.
  7228. {string1,string2,...}
  7229. Braces enclose a list of strings to be matched. For example:
  7230. ck{ufio,vcon,cmai}.c matches ckufio.c, ckvcon.c, or ckcmai.c.
  7231. The strings may themselves contain metacharacters, bracket
  7232. lists, or indeed, other lists of strings, but (when matching
  7233. filenames) they may not contain directory separators.
  7234. Thus, the metacharacters in filenames (and in any other field
  7235. that can be a pattern, such as the IF MATCH pattern, SEND or GET
  7236. exception lists, etc) are:
  7237. * ? [ {
  7238. And within braces only, comma (,) is a metacharacter.
  7239. To include a metacharacter in a pattern literally, precede it with a
  7240. backslash '\' (or two if you are passing the pattern to a macro).
  7241. Examples:
  7242. send a*b ; Send all files whose names start with 'a' and end with 'b'.
  7243. send a?b ; Ditto, but the name must be exactly three characters long.
  7244. send a[a-z]b ; Ditto, but the second character must be a lowercase letter.
  7245. send a[x\-z]b ; Ditto, except the second character must be 'x', '-', or 'y'.
  7246. send a[ghi]b ; Ditto, except the second character must be 'g', 'h', or 'i'.
  7247. send a[?*]b ; Ditto, except the second character must be '?' or '*'.
  7248. send a[\?\*]b ; Same as previous.
  7249. send *?[a-z]* ; All files with names containing at least one character
  7250. ; that is followed by a lowercase letter.
  7251. Or, more practically:
  7252. send ck[cuw]*.[cwh] ; Send the UNIX C-Kermit source files.
  7253. To refer to the C-Kermit sources files and makefile all in one
  7254. filespec:
  7255. {{makefile,ck[cuw]*.[cwh]}}
  7256. (NOTE: if the entire pattern is a {stringlist}, you must enclose it it
  7257. TWO pairs of braces, since the SEND command strips the outer brace
  7258. pair, because of the "enclose in braces if the filename contains
  7259. spaces" rule).
  7260. If the makefile is called ckuker.mak:
  7261. ck[cuw]*.{[cwh],mak}
  7262. (NOTE: double braces are not needed here since the pattern does not
  7263. both begin and end with a brace.)
  7264. To add in all the C-Kermit text files:
  7265. ck[cuw]*.{[cwh],mak,txt}
  7266. All of these features can be used anywhere you would type a filename
  7267. that is allowed to contain wildcards.
  7268. When you are typing at the command prompt, an extra level of quoting is
  7269. required for the '?' character to defeat its regular function of
  7270. producing a list of files that match what you have typed so far, for
  7271. example:
  7272. send ck[cu]?
  7273. lists all the files whose names start with ckc and cku. If you quote
  7274. the question mark, it is used as a pattern-matching character, for
  7275. example:
  7276. send ck\?[ft]io.c
  7277. sends all the file and communications i/o modules for all the
  7278. platforms: ckufio.c, ckutio.c, ckvfio.c, ckvtio.c, etc.
  7279. If, however, a filename actually contains a question mark and you need
  7280. to refer to it on the command line, you must use three (3) backslashes.
  7281. For example, if the file is actually called ck?fio.c, you would use:
  7282. send ck\\\?fio.c
  7283. Further notes on quoting:
  7284. * A single backslash is sufficient for quoting a special character at
  7285. the command prompt or in a command file. However, when passing
  7286. patterns to macros you'll need double backslashes, and when
  7287. referring to these patterns within the macro, you'll need to use
  7288. \fcontents(\%1) (see Section 1.11.5). You should enclose macro
  7289. argument references in braces in case grouped arguments were
  7290. passed. Example:
  7291. define ismatch {
  7292. if match {\fcont(\%1)} {\fcont(\%2)} {
  7293. end 0 MATCH
  7294. } else {
  7295. end 1 NO MATCH
  7296. }
  7297. }
  7298. ismatch ab*yz a*\\**z ; Backslash must be doubled
  7299. ismatch {abc def xyz} *b*e*y* ; Braces must be used for grouping
  7300. * Watch out for possible conflicts between {} in filename patterns
  7301. and {} used for grouping multiple words into a single field, when
  7302. the pattern has outer braces. For example, in:
  7303. if match {abc xyz} {a* *z} echo THEY MATCH
  7304. braces must be used to group "abc xyz" into a single string. Kermit
  7305. strips off the braces before comparing the string with the pattern.
  7306. Therefore:
  7307. if match makefile {makefile,Makefile} echo THEY MATCH
  7308. does not work, but:
  7309. if match makefile {{makefile,Makefile}} echo THEY MATCH
  7310. does.
  7311. * If you use a pattern that has outer braces, like {*.txt,*.doc}, in
  7312. a field that accepts a pattern list (like SEND /EXCEPT:xxx), you'll
  7313. need to add two extra sets of outer braces:
  7314. send /except:{{{*.txt,*.doc}}} *.*
  7315. C-Kermit's new pattern matching capabilities are also used when
  7316. C-Kermit is in server mode, so now you can send requests such as:
  7317. get ck[cuw]*.[cwh]
  7318. to a C-Kermit server without having to tell it to SET WILD SHELL first.
  7319. Previously this would have required:
  7320. mget ckc*.c ckc*.w ckc*.h cku*.c cku*.w cku*.h ckw*.c ckw*.w ckw*.h
  7321. The new pattern matching features make SET WILD SHELL redundant, and
  7322. barring any objections, it will eventually be phased out. (One possible
  7323. reason for retaining it would be as an escape mechanism when Kermit
  7324. does not understand the underlying file system.)
  7325. By the way, patterns such as these are sometimes referred to as
  7326. "regular expressions", but they are not quite the same. In a true
  7327. regular expression (for example), "*" means "zero or more repetitions
  7328. of the previous item", so (for example), "([0-9]*)" would match zero or
  7329. more digits in parentheses. In Kermit (and in most shells), this
  7330. matches one digit followed by zero or more characters, within
  7331. parentheses. Here are some hints:
  7332. * Although you can't match any sequence of digits (or letters, etc),
  7333. you can match (say) 1, 2, or 3 of them in row. For example, the
  7334. following pattern matches Kermit backup files (with backup numbers
  7335. from 1 to 999):
  7336. *.~{[1-9],[1-9][0-9],[1-9][0-9][0-9]}~
  7337. * There is presently no NOT operator, so no way to match any
  7338. character or string EXCEPT the one(s) shown.
  7339. In other wildcarding news...
  7340. * You may now "send xxx" where "xxx" is a directory name, and this
  7341. will send all the files from the directory xxx, as if you had typed
  7342. "send xxx/*". You can also use the special shorthand "send ." to
  7343. send all the files from the current directory.
  7344. * To easily skip over backup files (the ones whose names end like
  7345. .~22~) when sending, you can use SEND /NOBACKUP (seeSection
  7346. 4.0.6 for details).
  7347. * When choosing Kermit to expand wildcards, rather than the shell,
  7348. you can choose whether "dot files" -- files whose names begin with
  7349. ".", which are normally "invisible" -- should be matched:
  7350. SET WILD KERMIT /NO-MATCH-DOT-FILES (this is the default)
  7351. SET WILD KERMIT /MATCH-DOT-FILES (this allows matching of "." files)
  7352. or include the /DOTFILES or /NODOTFILES switch on the command you
  7353. are using, such as SEND or DIRECTORY.
  7354. * Commands such as DIRECTORY and SEND allow recursive directory
  7355. traversal. There are also new functions for this to use in scripts.
  7356. See Section 4.11 for details.
  7357. When building file lists in UNIX, C-Kermit follows symbolic links.
  7358. Because of this, you might encounter any or all of the following
  7359. phenomena:
  7360. * Multiple copies of the same file; e.g. one from its real directory
  7361. and others from links to its real directory, if both the real
  7362. directory and the links to it are in the wildcard expansion list.
  7363. * A command might unexpectedly "hang" for a long time because an NFS
  7364. link might not be responding, or the directory you are looking at
  7365. contains a link to a huge directory tree (example: "directory
  7366. /recursive /etc" when /etc/spool is a symlink to /var/spool, which
  7367. is a large organization's incoming email directory, containing tens
  7368. of thousands of subdirectories).
  7369. The size of the file list that Kermit can build is limited in most
  7370. C-Kermit implementations. The limit, if any, depends on the
  7371. implementation. Use the SHOW FEATURES command and look in the
  7372. alphabetized options list for MAXWLD to see the value.
  7373. 4.9.2. In Kermit 95
  7374. Kermit 95 1.1.19 and later uses the same pattern matching syntax as in
  7375. UNIX, but (as always) you will encounter numerous difficulties if you
  7376. use backslash (\) as the directory separator. In any command where K95
  7377. parses filenames itself (that is, practically any file-oriented command
  7378. except RUN), you can use forward slash (/) as the directory separator
  7379. to avoid all the nasty conflicts.
  7380. 4.9.3. In VMS, AOS/VS, OS-9, VOS, etc.
  7381. Platforms other than UNIX, Windows 95/98/NT, and OS/2 have their own
  7382. filename matching capabilities that are, in general, different from
  7383. Kermit's built-in ones and in any case might conflict with them. For
  7384. example, [] encloses directory names in VMS.
  7385. Nevertheless you can still use all the pattern-matching capabilities
  7386. described in Section 4.9.1 by loading a file list into an array
  7387. (e.g. with \ffiles(*,&a), see Section 4.11.3) and then using IF
  7388. MATCH on the members.
  7389. 4.10. Additional Pathname Controls
  7390. In version 6.0 and earlier, C-Kermit's SET { SEND, RECEIVE } PATHNAMES
  7391. command had only ON and OFF as options. In version 7.0, there are more
  7392. choices:
  7393. SET SEND PATHNAMES OFF
  7394. When sending a file, strip all disk/directory information from
  7395. the name. Example: "send /usr/olga/letters/oofa.txt" sends the
  7396. file as "oofa.txt". This applies to actual filenames, not to any
  7397. as-name you might specify.
  7398. SET SEND PATHNAMES RELATIVE
  7399. When sending a file, leave the pathname on as given. For
  7400. example, if your current directory is /usr/olga, "send
  7401. letters/oofa.txt" sends the file as "letters/oofa.txt", not
  7402. "/usr/olga/letters/oofa.txt" or "letters.txt".
  7403. SET SEND PATHNAMES ABSOLUTE
  7404. When sending a file, convert its name to the full, absolute
  7405. local pathname. For example, if your current directory is
  7406. /usr/olga, "send letters/oofa.txt" sends the file as
  7407. "/usr/olga/letters/oofa.txt". NOTE: Even with this setting,
  7408. device and/or node names are not included. For example, in VMS,
  7409. any node or device name is stripped; in Windows or OS/2, any
  7410. disk letter is stripped.
  7411. SET RECEIVE PATHNAMES OFF
  7412. When receiving a file, strip all disk/directory information from
  7413. the name before attempting to store it. This applies to incoming
  7414. filename, not to any as-name you might specify. Example: If a
  7415. file arrives under the name "/usr/olga/letters/oofa.txt" it is
  7416. stored simply as "oofa.txt" in your download directory or, if no
  7417. download directory has been specified, in your current
  7418. directory.
  7419. SET RECEIVE PATHNAMES RELATIVE
  7420. When receiving a file, leave the pathname on as it appears in
  7421. the incoming name, but if the incoming name appears to be
  7422. absolute, make it relative to your current or download
  7423. directory. Examples:
  7424. + "oofa.txt" is stored as "oofa.txt".
  7425. + "letters/oofa.txt" is stored as "letters/oofa.txt"; the
  7426. "letters" subdirectory is created if it does not already
  7427. exist.
  7428. + "/usr/olga/letters/oofa.txt" is stored as
  7429. "usr/olga/letters/oofa.txt" in your current or download
  7430. directory, and the "usr", "usr/olga", etc, directories are
  7431. created if they do not exist.
  7432. SET RECEIVE PATHNAMES ABSOLUTE
  7433. The incoming filename is used as given. Thus it cannot be stored
  7434. unless the given path (if any) already exists or can be created.
  7435. In this case, node, device, or disk designations are NOT
  7436. stripped, since they most likely were given explicitly by the
  7437. user as an as-name, meant to be used as given.
  7438. SET RECEIVE PATHNAMES AUTO
  7439. This is the default, and means RELATIVE if the sender tells me
  7440. it is a recursive transfer, OFF otherwise.
  7441. Set FILE NAMES CONVERTED now also affects pathnames too. When PATHNAMES
  7442. are RELATIVE or ABSOLUTE and FILE NAMES are CONVERTED, the file sender
  7443. converts its native directory-name format to UNIX format, and the file
  7444. receiver converts from UNIX format to its native one; thus UNIX format
  7445. is the common intermediate representation for directory hierarchies, as
  7446. it is in the ZIP/UNZIP programs (which is why ZIP archives are
  7447. transportable among, UNIX, DOS, and VMS).
  7448. Here's an example in which a file is sent from Windows to UNIX with
  7449. relative pathnames and FILE NAMES CONVERTED:
  7450. Source name Intermediate name Destination Name
  7451. C:\K95\TMP\OOFA.TXT K95/TMP/OOFA.TXT k95/tmp/oofa.txt
  7452. In a more complicated example, we send the same file from Windows to
  7453. VMS:
  7454. Source name Intermediate name Destination Name
  7455. C:\K95\TMP\OOFA.TXT K95/TMP/OOFA.TXT [.K95.TMP]OOFA.TXT
  7456. (Note that disk letters and device designations are always stripped
  7457. when pathnames are relative).
  7458. As you can imagine, as more and more directory formats are considered,
  7459. this approach keeps matters simple: on each platform, Kermit must know
  7460. only its own local format and the common intermediate one. In most
  7461. cases, the receiver can detect which format is used automatically.
  7462. 4.11. Recursive SEND and GET: Transferring Directory Trees
  7463. C-Kermit 7.0 in selected versions (UNIX, VMS, VOS, AOS/VS, Windows, and
  7464. OS/2 at this writing) now permits the SEND command to traverse
  7465. directories "recursively" if you ask it to; that is, to send files from
  7466. the current or specified directory and all of its subdirectories too,
  7467. and their subdirectories, etc. (Some other commands can do this too,
  7468. including DIRECTORY.)
  7469. This feature is new to UNIX, Windows, VOS, and OS/2. VMS and AOS/VS
  7470. have always included "wildcard" or "template" characters that allow
  7471. this, and in this case, recursive directory traversal could happen
  7472. behind Kermit's back, i.e. Kermit does not have to do it itself (in
  7473. VMS, the notation is "[...]" or "[directory...]"; in AOS/VS is "#"). In
  7474. C-Kermit 7.0, however, SEND /RECURSIVE is supported by C-Kermit itself
  7475. for VMS.
  7476. 4.11.1. Command-Line Options
  7477. To descend a directory tree when sending files, use the -L command-line
  7478. option to indicate that the send operation is to be recursive, and
  7479. include a name or pattern to be sent. When giving a pattern, you should
  7480. enclose it in quotes to prevent the shell from expanding it. Examples:
  7481. $ kermit -Ls "/usr/olga/*" # send all of Olga's files in all her directories
  7482. $ kermit -Ls foo.txt # send all foo.txt files in this directory tree
  7483. $ kermit -Ls "*.txt" # send all .txt files in this directory tree
  7484. $ kermit -Ls "letters/*" # send all files in the letters directory tree
  7485. $ kermit -Ls letters # send all files in the letters directory tree
  7486. $ kermit -Ls "*" # send all files in this directory tree
  7487. $ kermit -Ls . # UNIX only: send all files in this directory tree
  7488. $ kermit -s . # UNIX only: a filename of . implies -L
  7489. If you let the shell expand wildcards, Kermit only sends files whose
  7490. names match files in the current or given directory, because the shell
  7491. replaces an unquoted wildcard expression with the list of matching
  7492. files -- and the shell does not build recursive lists. Note that the
  7493. "." notation for the tree rooted at the current directory is allowed
  7494. only in UNIX, since in Windows and OS/2, it means "*.*" (nonrecursive).
  7495. 4.11.2. The SEND /RECURSIVE Command
  7496. If you include the /RECURSIVE switch in a SEND (or MOVE, or similar)
  7497. command, it means to descend the current or specified directory tree
  7498. searching for files whose names match the given name or pattern. Since
  7499. this is not terribly useful unless you also include pathnames with the
  7500. outbound files, the /RECURSIVE switch also includes an implicit
  7501. /PATHNAMES:RELATIVE switch (which you can undo by including an explicit
  7502. /PATHNAMES switch after the /RECURSIVE switch).
  7503. Examples:
  7504. SEND /RECURSIVE *
  7505. Sends all of the files in the current directory and all the
  7506. files in all of its subdirectories, and all of their
  7507. subdirectories, etc, including their relative pathnames. Empty
  7508. directories are not sent.
  7509. SEND /RECURSIVE /PATHNAMES:ABSOLUTE *
  7510. Sends all of the files in the current directory and all the
  7511. files in all of its subdirectories, and all of their
  7512. subdirectories, etc, including their absolute pathnames.
  7513. SEND /RECURSIVE /PATHNAMES:OFF *
  7514. Sends all of the files in the current directory and all the
  7515. files in all of its subdirectories, and all of their
  7516. subdirectories, etc, without pathnames.
  7517. SEND /RECURSIVE /usr/olga/*
  7518. Sends all of the files in the /usr/olga directory and all the
  7519. files in all of its subdirectories, and all of their
  7520. subdirectories, etc.
  7521. SEND /RECURSIVE /usr/olga (or /usr/olga/)
  7522. Same as above. If the name is a directory name (with or without
  7523. a trailing slash), its files are sent, and those of its
  7524. subdirectories, and their subdirectories, etc (seeSection
  7525. 4.9).
  7526. SEND /RECURSIVE /TEXT /usr/olga/*.txt
  7527. As above, but only files whose names end with ".txt" are sent,
  7528. and they are sent in text mode (as they would be by default
  7529. anyway if SET FILE PATTERNS is ON or AUTO).
  7530. SEND .
  7531. UNIX only: Send all the files in the current directory.
  7532. SEND /RECURSIVE .
  7533. UNIX only: Sends all of the files in the current directory and
  7534. all of its subdirectories, etc ( Section 4.9).
  7535. The /RECURSIVE switch is different from most other switches in that its
  7536. effect is immediate (but still local to the command in which it is
  7537. given), because it determines how filenames are to be parsed. For
  7538. example, "send *.txt" fails with a parse error ("No files match") if
  7539. there are no *.txt files in the current directory, but "send /recursive
  7540. *.txt" succeeds if there are ".txt" files anywhere in the tree rooted
  7541. at the current directory.
  7542. The /RECURSIVE switch also affects the file lists displayed if you type
  7543. "?" in a filename field. "send ./?" lists the regular files in the
  7544. current directory, but "send /recursive ./?" lists the entire directory
  7545. tree rooted at the current directory.
  7546. 4.11.3. The GET /RECURSIVE Command
  7547. In a client/server setting, the client can also request a recursive
  7548. transfer with:
  7549. GET /RECURSIVE [ other switches ] remote-filespec [ local-spec ]
  7550. In which remote file specification can be a directory name, a filename,
  7551. a wildcard, or any combination. If the local-spec is not given (and
  7552. PATHNAMES are RELATIVE), incoming files and directories go into the
  7553. current local directory. If local-spec is given and is a directory, it
  7554. becomes the root of the tree into which the incoming files and
  7555. directories are placed. If local-spec has the syntax of a directory
  7556. name (e.g. in UNIX it ends with /), C-Kermit creates the directory and
  7557. then places the incoming files into it. If local-spec is a filename
  7558. (not recommended), then all incoming files are stored with that name
  7559. with collisions handled according to the FILE COLLISION setting.
  7560. Again, the normal method for transferring directory trees uses relative
  7561. pathnames, and this is the default when the sender has been given the
  7562. /RECURSIVE switch. The action at the receiver depends on its RECEIVE
  7563. PATHNAMES setting. The default is AUTO, meaning that if the sender
  7564. tells it to expect a recursive transfer, then it should automatically
  7565. switch to relative pathnames for this transfer only; otherwise it obeys
  7566. the RECEIVE PATHNAMES setting of OFF, ABSOLUTE, or RELATIVE.
  7567. What happens if a file arrives that has an absolute pathname, when the
  7568. receiver has been told to use only relative pathnames? As a security
  7569. precaution, in this case the receiver treats the name as if it was
  7570. relative. For example, if a file arrives as:
  7571. /usr/olga/oofa.txt
  7572. The receiver creates a "usr" subdirectory in its current directory, and
  7573. then an "olga" subdirectory under the "usr" subdirectory in which to
  7574. store the incoming file.
  7575. Suppose, however there is a sequence of directories:
  7576. /usr/olga/a/b/c/d/
  7577. in which "a" contains nothing but a subdirectory "b", which in turn
  7578. contains nothing but a subdirectory "c", which in turn contains nothing
  7579. but a subdirectory "d", which contains nothing at all. Thus there are
  7580. no files in the "/usr/olga/a/" tree, and so it is not sent, and
  7581. therefore it is not reproduced on the target computer.
  7582. 4.11.4. New and Changed File Functions
  7583. C-Kermit 7.0 adds the following functions:
  7584. \ffiles(pattern[,&a])
  7585. This function has been changed to match only regular files in
  7586. the current or given directory, and to take an optional array
  7587. name as a second argument (explained below).
  7588. \fdirectories(pattern[,&a])
  7589. Returns the number of directories that match the given pattern.
  7590. If the pattern does not include a directory, then the search is
  7591. performed in the current directory.
  7592. \frfiles(pattern[,&a])
  7593. Returns the number of files in the current or given directory
  7594. and all of its subdirectories, and their subdirectories, etc,
  7595. that match the given pattern. Warning -- this one can take quite
  7596. some time if performed at the root of a large directory tree.
  7597. \frdirectories(pattern[,&a])
  7598. Returns the number of directories in the current or given
  7599. directory and all of its subdirectories, and their
  7600. subdirectories, etc, that match the given pattern.
  7601. Each of these functions builds up a list of files to be returned by the
  7602. \fnextfile() function, just as \ffiles() always has done. (This can
  7603. also be done with the /ARRAY switch of the DIRECTORY command; see
  7604. Sections 4.5.1 and7.10).
  7605. Each of these functions can be given an array name as an optional
  7606. second argument. If an array name is supplied, the array will contain
  7607. the number of files as its 0th element, and the filenames in elements 1
  7608. through last. If the array already existed, its previous contents are
  7609. lost. For example, if the current directory contains two files,
  7610. oofa.txt and foo.bar, then "\ffiles(*,&a)" creates an array \&a[] with
  7611. a dimension of 2, containing the following elements:
  7612. \&a[0] = 2
  7613. \&a[1] = oofa.txt
  7614. \&a[2] = foo.bar
  7615. If no files match the specification given in the first argument, the
  7616. array gets a dimension of 0, which is the same as undeclaring the
  7617. array.
  7618. Note that the order in which the array is filled (and in which
  7619. \fnextfile() returns filenames) is indeterminate (but seeSection
  7620. 7.10.5).
  7621. Here's an example that builds and prints a list of all the file whose
  7622. names end in .txt in the current directory and all its descendents:
  7623. asg \%n \frfiles(*.txt)
  7624. declare \&a[\%n]
  7625. for \%i 1 \%n 1 {
  7626. asg \&a[\%i] \fnextfile()
  7627. echo \flpad(\%i,4). "\&a[\%i]"
  7628. }
  7629. Alternatively, using the array method, and then printing the filenames
  7630. in alphabetic order (see Section 7.10.3 and7.10.5):
  7631. asg \%n \frfiles(*.txt,&a)
  7632. sort &a
  7633. for \%i 1 \%n 1 {
  7634. echo \flpad(\%i,4). "\&a[\%i]"
  7635. }
  7636. Or even more simply:
  7637. asg \%n \frfiles(*.txt,&a)
  7638. sort &a
  7639. show array &a
  7640. As noted elsewhere, the file lists built by \ffiles(), \frfiles(), etc,
  7641. are now "safe" in the sense that SEND and other file-related commands
  7642. can reference \fnextfile() without resetting the list:
  7643. set send pathnames relative
  7644. for \%i 1 \frfiles(*.txt) 1 {
  7645. asg \%a \fnextfile()
  7646. echo Sending \%a...
  7647. send \%a
  7648. if fail break
  7649. }
  7650. Copying to an array (as shown on p.398 ofUsing C-Kermit 2nd Ed)
  7651. is no longer necessary.
  7652. 4.11.5. Moving Directory Trees Between Like Systems
  7653. 4.11.5.1. UNIX to UNIX
  7654. Transferring a directory tree from one computer to another replicates
  7655. the file sender's arrangement of files and directories on the file
  7656. receiver's computer. Normally this is done using relative pathnames,
  7657. since the user IDs might not be identical on the two computers. Let's
  7658. say both computers are UNIX based, running C-Kermit 7.0 or later. On
  7659. the sending computer (leaving out the connection details, etc):
  7660. C-Kermit> cd /usr/olga
  7661. C-Kermit> send /recursive .
  7662. The /RECURSIVE switch tells C-Kermit to descend through the directory
  7663. tree and to include relative pathnames on outbound filenames.
  7664. On the receiving computer:
  7665. C-Kermit> mkdir olgas-files ; Make a new directory.
  7666. C-Kermit> cd olgas-files ; CD to it.
  7667. C-Kermit> receive /recursive ; = /PATHNAMES:RELATIVE
  7668. Each Kermit program recognizes that the other is running under UNIX and
  7669. switches to binary mode and literal filenames automatically.
  7670. Directories are automatically created on the receiving system as
  7671. needed. File dates and permissions are automatically reproduced from
  7672. source to destination.
  7673. 4.11.5.2. VMS to VMS
  7674. To send recursively from VMS, simply include the /RECURSIVE switch, for
  7675. example at the sender:
  7676. $ kermit
  7677. C-Kermit> cd [olga]
  7678. C-Kermit> send /recursive *.*;0
  7679. And at the receiver:
  7680. C-Kermit> cd [.olga]
  7681. C-Kermit> receive /recursive
  7682. The notation "..." within directory brackets in VMS means "this
  7683. directory and all directories below it"; the /RECURSIVE switch, when
  7684. given to the sender, implies the use of "..." in the file specification
  7685. so you don't have to include "..."; but it makes no difference if you
  7686. do:
  7687. $ kermit
  7688. C-Kermit> send /recursive [olga...]*.*;0
  7689. And at the receiver:
  7690. C-Kermit> cd [.olga]
  7691. C-Kermit> receive /recursive
  7692. In either case, since both systems recognize each other as VMS, they
  7693. switch into LABELED transfer mode automatically.
  7694. 4.11.6. Moving Directory Trees Between Unlike Systems
  7695. There are several difficulties with recursive transfers between unlike
  7696. systems:
  7697. * File formats can be different, especially text files character sets
  7698. and record formats. This can now be handled by using SET FILE
  7699. PATTERN, SET FILE TEXT-PATTERNS, and SET FILE BINARY-PATTERNS
  7700. ( Section 4.3).
  7701. * File naming conventions are different. For example, one system
  7702. might allow (and use) longer filenames than the other. You can tell
  7703. Kermit how to handle file names with the normal "set file names"
  7704. and "set file collision" mechanisms. Most modern Kermits are fairly
  7705. tolerant of illegal filenames and should not fail simply because of
  7706. an incoming filename; rather, it will do its best to convert it to
  7707. a recognizable and unique legal filename.
  7708. * Directory notations can be different, e.g. backslashes instead of
  7709. slashes, brackets, parentheses, spaces, etc. But this is now
  7710. handled by converting pathnames to a standard format during
  7711. transfer ( Section 4.10).
  7712. So now, for the first time, it is possible to send directory trees
  7713. among any combination of UNIX, DOS, Windows, OS/2, VMS, AOS/VS, etc.
  7714. Here's an example sending files from an HP-UX system (where text files
  7715. are encoded in the HP Roman8 character set) to a PC with K95 (where
  7716. text files are encoded in CP850):
  7717. Sender:
  7718. cd xxx ; CD to root of source tree
  7719. set file type binary ; Default transfer mode
  7720. set file character-set hp-roman8 ; Local character set for text files
  7721. set xfer character-set latin1 ; Transfer character set
  7722. set file patterns on ; Enable automatic file-type switching...
  7723. set file binary-patterns *.Z *.gz *.o ; based on these patterns...
  7724. set file text-patterns *.txt *.c *.h ; for binary and text files.
  7725. send /recursive * ; Send all the file in this directory tree
  7726. Receiver:
  7727. cd yyy ; CD to root of destination tree
  7728. set file character-set cp850 ; Local character set for text files
  7729. receive /pathnames:relative ; Receive with pathnames
  7730. Notes:
  7731. * Replace "xxx" and "yyy" with the desired directories.
  7732. * Replace the file character sets appropriately.
  7733. * Change the patterns as needed (or just use the built-in default
  7734. lists).
  7735. * SEND /RECURSIVE also implies /PATHNAMES:RELATIVE.
  7736. * The file sender tells the file receiver the transfer mode of each
  7737. file.
  7738. * The file sender tells the file receiver the transfer character set.
  7739. * By default, destination file dates will be the same as on the
  7740. source.
  7741. * Many of the settings shown might already be set by default.
  7742. * SeeSections 4.3,4.10, and4.15 for additional
  7743. explanation.
  7744. If you are refreshing an existing directory on the destination
  7745. computer, use "set file collision update" or other appropriate file
  7746. collision option to handle filename collisions.
  7747. 4.12. Where Did My File Go?
  7748. Now that Kermit can be started by clicking on desktop icons (thus
  7749. obscuring the concept of "current directory"), and can have a download
  7750. directory, and can create directories for incoming files on the fly,
  7751. etc, sometimes it is easy to lose a file after transfer. Of course, if
  7752. you keep a transaction log:
  7753. LOG TRANSACTIONS
  7754. it will record the fate and final resting place of each file. But in
  7755. case you did not keep a log, the new command:
  7756. WHERE
  7757. added in C-Kermit 7.0, gives you as much information as it has about
  7758. the location of the last files transferred, including the pathname
  7759. reported by the receiving Kermit, if any, when C-Kermit is the sender.
  7760. This information was also added to SHOW FILE in somewhat less detail.
  7761. 4.13. File Output Buffer Control
  7762. (UNIX only). The new command SET FILE OUTPUT lets you control how
  7763. incoming files are written to disk:
  7764. SET FILE OUTPUT BUFFERED [ size ]
  7765. Chooses buffered file output; this is the default. UNIX does its
  7766. normal sort of disk buffering. The optional size specifies
  7767. Kermit's own file output buffer size, and therefore the
  7768. frequency of disk accesses (write() system calls) -- the bigger
  7769. the size, the fewer the disk accesses.
  7770. SET FILE OUTPUT UNBUFFERED [ size ]
  7771. This forces each file output write() call to actually commit the
  7772. data to disk immediately. Choosing this option will usually slow
  7773. file reception down.
  7774. SET FILE OUTPUT BLOCKING
  7775. Write() calls should not return until they are complete. This is
  7776. the normal setting, and it lets Kermit detect disk-write errors
  7777. immediately.
  7778. SET FILE OUTPUT NONBLOCKING
  7779. Write() calls should return immediately. This can speed up file
  7780. reception, but also delay the detection of disk-write errors.
  7781. Experimentation with these parameters should be harmless, and might (or
  7782. might not) have a perceptible, even dramatic, effect on performance.
  7783. 4.14. Improved Responsiveness
  7784. In version 7.0, C-Kermit's file-transfer protocol engine has been tuned
  7785. for additional speed and responsiveness.
  7786. * Binary-mode transfers over 8-bit connections, a very common case,
  7787. are now handled in a special way that minimizes overhead.
  7788. * SET TRANSFER CRC-CALCULATION is now OFF by default, rather than ON.
  7789. (This affects only the overall per-transfer CRC, \v(crc16), not the
  7790. per-packet CRCs)
  7791. * Connection loss during file transfer is now detected immediately in
  7792. most cases on Internet connections and on serial connections when
  7793. CARRIER-WATCH is not set to OFF.
  7794. 4.15. Doubling and Ignoring Characters for Transparency
  7795. The following commands were added in 7.0, primarily to allow successful
  7796. file transfer through ARPAnet TACs and with Honeywell DPS6 systems, but
  7797. can be used in any setting where they might be needed:
  7798. SET SEND DOUBLE-CHAR { [ char [ char [ ... ] ] ], NONE }
  7799. Tells C-Kermit to double the specified characters (use decimal
  7800. notation) in packets that it sends. For example, if you are
  7801. sending files through a device that uses @ as an escape
  7802. character, but allows you to send a single copy of @ through by
  7803. doubling it, use "set send double 64".
  7804. SET RECEIVE IGNORE-CHAR [ char [ char [ ... ] ] ]
  7805. Tells C-Kermit to ignore the specified character(s) in incoming
  7806. packets. Use this, for example, when something between the
  7807. sender and receiver is inserting linefeeds for wrapping, NULs
  7808. for padding, etc.
  7809. 4.16. New File-Transfer Display Formats
  7810. SET TRANSFER DISPLAY { BRIEF, CRT, FULLSCREEN, NONE, SERIAL }
  7811. Selects the file-transfer display format.
  7812. BRIEF is the new one. This writes one line to the screen per file,
  7813. showing the file's name, transfer mode, size, the status of the
  7814. transfer, and when the transfer is successful, the effective data rate
  7815. in characters per second (CPS). Example:
  7816. SEND ckcfn3.o (binary) (59216 bytes): OK (0.104 sec, 570206 cps)
  7817. SEND ckcfns.o (binary) (114436 bytes): OK (0.148 sec, 772006 cps)
  7818. SEND ckcmai.c (text) (79147 bytes): OK (0.180 sec, 438543 cps)
  7819. SEND ckcmai.o (binary) (35396 bytes): OK (0.060 sec, 587494 cps)
  7820. SEND ckcnet.o (binary) (62772 bytes): REFUSED
  7821. SEND ckcpro.o (binary) (121448 bytes): OK (0.173 sec, 703928 cps)
  7822. SEND ckcpro.w (text) (63687 bytes): OK (0.141 sec, 453059 cps)
  7823. SEND makefile (text) (186636 bytes): OK (0.444 sec, 420471 cps)
  7824. SEND wermit (binary) (1064960 bytes): OK (2.207 sec, 482477 cps)
  7825. Note that transfer times are now obtained in fractional seconds, rather
  7826. than whole seconds, so the CPS figures are more accurate (the display
  7827. shows 3 decimal places, but internally the figure is generally precise
  7828. to the microsecond).
  7829. 4.17. New Transaction Log Formats
  7830. The new command:
  7831. SET TRANSACTION-LOG { VERBOSE, FTP, BRIEF [ separator ] }
  7832. lets you choose the format of the transaction log. VERBOSE (the
  7833. default) indicates the traditional format described in the book. BRIEF
  7834. and FTP are new. This command must be given prior to the LOG
  7835. TRANSACTION command if a non-VERBOSE type is desired.
  7836. 4.17.1. The BRIEF Format
  7837. BRIEF chooses a one-line per file format suitable for direct
  7838. importation into databases like Informix, Oracle, or Sybase, in which:
  7839. * Each record has 8 fields.
  7840. * Fields are separated by a non-alphanumeric separator character.
  7841. * The default separator character is comma (,).
  7842. * Any field containing the separator character is enclosed in
  7843. doublequotes.
  7844. * The final field is enclosed in doublequotes.
  7845. The fields are:
  7846. 1. Date in yyyymmdd format
  7847. 2. Time in hh:mm:ss format
  7848. 3. Action: SEND or RECV
  7849. 4. The local filename
  7850. 5. The size of the file
  7851. 6. The transfer mode (text, binary, image, labeled)
  7852. 7. The status of the transfer: OK or FAILED
  7853. 8. Additional status-dependent info, in doublequotes.
  7854. Examples:
  7855. 20000208,12:08:52,RECV,/u/olga/oofa.txt,5246,text,OK,"0.284sec 18443cps"
  7856. 20000208,12:09:31,SEND,/u/olga/oofa.exe,32768,binary,OK,"1.243sec 26362cps"
  7857. 20000208,12:10:02,SEND,"/u/olga/a,b",10130,text,FAILED,"Refused: date"
  7858. Note how the filename is enclosed in doublequotes in the final example,
  7859. because it contains a comma.
  7860. To obtain BRIEF format, you must give the SET TRANSACTION-LOG BRIEF
  7861. command before the LOG TRANSACTIONS command. (If you give them in the
  7862. opposite order, a heading is written to the log by the LOG command.)
  7863. 4.17.2. The FTP Format
  7864. SET TRANSACTION-LOG FTP (available only in UNIX) chooses a format that
  7865. is compatible with the WU-FTPD (Washington University FTP daemon) log,
  7866. and so can be processed by any software that processes the WU-FTPD log.
  7867. It logs only transfers in and out, both successful and failed (but
  7868. success or failure is not indicated, due to lack of a field in the
  7869. WU-FTPD log format for this purpose). Non-transfer events are not
  7870. recorded.
  7871. Unlike other logs, the FTP-format transaction log is opened in append
  7872. mode by default. This allows you to easily keep a record of all your
  7873. kermit transfers, and it also allows the same log to be shared by
  7874. multiple simultaneous Kermit processes or (permissions permitting)
  7875. users. You can, of course, force creation of a new logfile by
  7876. specifying the NEW keyword after the filename, e.g.
  7877. log transactions oofa.log new
  7878. All records in the FTP-style log are in a consistent format. The first
  7879. field is fixed-length and contains spaces; subsequent fields are
  7880. variable length, contain no spaces, and are separated by one or more
  7881. spaces. The fields are:
  7882. Timestamp
  7883. This is an asctime-style timestamp, example: "Wed Sep 16
  7884. 20:19:05 1999" It is always exactly 24 characters long, and the
  7885. subfields are always in fixed positions.
  7886. Elapsed time
  7887. The whole number of seconds required to transfer the file, as a
  7888. string of decimal digits, e.g. "24".
  7889. Connection
  7890. The name of the network host to which C-Kermit is connected, or
  7891. the name of the serial device through which it has dialed (or
  7892. has a direct connection), or "/dev/tty" for transfers in remote
  7893. mode.
  7894. Bytes transferred
  7895. The number of bytes transferred, decimal digits, e.g. "1537904".
  7896. Filename
  7897. The name of the file that was transferred, e.g.
  7898. "/pub/ftp/kermit/a/README.TXT". If the filename contains any
  7899. spaces or control characters, each such character is replaced by
  7900. an underscore ('_') character.
  7901. Mode
  7902. The letter 'b' if the file was transferred in binary mode, or
  7903. 'a' if it was transferred in text (ASCII) mode.
  7904. Options
  7905. This field always contains an underscore ('_') character.
  7906. Direction
  7907. The letter 'o' if the file was transferred Out, and 'i' if the
  7908. file was transferred In.
  7909. User class
  7910. The letter 'r' indicates the file was transferred by a Real
  7911. user.
  7912. User identification
  7913. The ID of the user who transferred the file.
  7914. Server identification
  7915. The string "kermit". This distinguishes a Kermit transfer log
  7916. record from a WU-FTPD record, which contains "ftp" in this
  7917. field.
  7918. Authentication class
  7919. The digit '1' if we know the user's ID on the client system,
  7920. otherwise '0'. Currently, always '0'.
  7921. Authenticated user
  7922. If the authentication class is '1', this is the user's ID on the
  7923. client system. Otherwise it is an asterisk ('*'). Currently it
  7924. is always an asterisk.
  7925. Examples:
  7926. Thu Oct 22 17:42:48 1998 0 * 94 /usr/olga/new.x a _ i r olga kermit 0 *
  7927. Thu Oct 22 17:51:29 1998 1 * 147899 /usr/olga/test.c a _ o r olga kermit 0 *
  7928. Thu Oct 22 17:51:44 1998 1 * 235 /usr/olga/test.o b _ i r olga kermit 0 *
  7929. Fri Oct 23 12:10:25 1998 0 * 235 /usr/olga/x.ksc a _ o r olga kermit 0 *
  7930. Note that an ftp-format transaction log can also be selected on the
  7931. Kermit command line as follows:
  7932. kermit --xferfile:filespec
  7933. This is equivalent to:
  7934. SET TRANSACTION-LOG FTP
  7935. LOG TRANSACTIONS filespec APPEND
  7936. Conceivably it could be possible to have a system-wide shared Kermit
  7937. log, except that UNIX lacks any notion of an append-only file; thus any
  7938. user who could append to the log could also delete it (or alter it).
  7939. This problem could be worked around using setuid/setgid tricks, but
  7940. these would most likely interfere with the other setuid/setgid tricks
  7941. C-Kermit must use for getting at dialout devices and UUCP logfiles.
  7942. 4.18. Unprefixing NUL
  7943. As of 6.1.193 Alpha.10, C-Kermit can finally send and receive
  7944. file-transfer packets in which NUL (ASCII 0) is unprefixed (no more
  7945. NUL-terminated packets!). NUL is, of course, extremely prevalent in
  7946. binary files such as executables, and this has been a significant
  7947. source of packet overhead. For example, when transferring itself (the
  7948. SunOS C-Kermit executable) with minimal prefixing and 9000-byte
  7949. packets, we see:
  7950. File size: 1064960
  7951. Packet chars with 0 prefixed: 1199629 overhead = 12.65%
  7952. Packet chars with 0 unprefixed: 1062393 overhead = -0.03%
  7953. Transfer rates go up accordingly, not only because of the reduced
  7954. amount of i/o, but also because less computation is required on each
  7955. end.
  7956. 4.19. Clear-Channel Protocol
  7957. Now that C-Kermit itself is capable of sending and receiving any byte
  7958. at all on a clear channel ( Section 4.18), it is, for the first
  7959. time, in a position to negotiate a clear channel with the other Kermit,
  7960. giving it permission (but not requiring it) to unprefix any and all
  7961. characters that it knows are safe. In general this means all but the
  7962. Kermit start-of-packet character (normally Ctrl-A), Carriage Return
  7963. (not only Kermit's end-of-packet character, but also treated specially
  7964. on Telnet NVT links), and IAC (255, also special to Telnet).
  7965. By default, C-Kermit will say it has a clear channel only if it has
  7966. opened a TCP socket. Since the Kermit program on the far end of a
  7967. TCP/IP connection generally does not know it has a TCP/IP connection,
  7968. it will not announce a clear channel unless it has been told to do so.
  7969. The command is:
  7970. SET CLEAR-CHANNEL { ON, OFF, AUTO }
  7971. AUTO is the default, meaning that the clear-channel status is
  7972. determined automatically from the type of connection. ON means to
  7973. announce a clear channel, OFF means not to announce it. Use SHOW
  7974. STREAMING ( Section 4.20) to see the current CLEAR-CHANNEL status.
  7975. Synonym: SET CLEARCHANNEL.
  7976. CLEAR-CHANNEL is also set if you start C-Kermit with the -I switch (see
  7977. Section 4.20).
  7978. Whenever a clear channel is negotiated, the resulting control-character
  7979. unprefixing is "sticky"; that is, it remains in effect after the
  7980. transfer so you can use SHOW CONTROL to see what was negotiated.
  7981. You can also see whether a clear channel was negotiated in the
  7982. STATISTICS /VERBOSE Display.
  7983. The advantage of the clear channel feature is that it can make file
  7984. transfers go faster automatically. The disadvantage would be
  7985. file-transfer failures if the channel is not truly clear, for example
  7986. if C-Kermit made a Telnet connection to a terminal server, and then
  7987. dialed out from there; or if C-Kermit made an Rlogin connection to host
  7988. and then made a Telnet connection from there to another host. If a file
  7989. transfer fails on a TCP/IP connection, use SHOW CONTROL to check
  7990. whether control characters became unprefixed as a result of protocol
  7991. negotiations, and/or SHOW STREAMING ( Section 4.20) to see if
  7992. "clear-channel" was negotiated. If this happened, use SET CLEAR-CHANNEL
  7993. OFF and SET PREFIXING CAUTIOUS (or whatever) to prevent it from
  7994. happening again.
  7995. 4.20. Streaming Protocol
  7996. A new Kermit protocol option called "streaming" was added in C-Kermit
  7997. 7.0. The idea is that if the two Kermit partners have a reliable
  7998. transport (such as TCP/IP or X.25) between them, then there is no need
  7999. to send ACKs for Data packets, or NAKs, since a reliable transport
  8000. will, by definition, deliver all packets in order and undamaged. On
  8001. such a connection, streaming cuts down not only on Kermit program
  8002. overhead (switching back and forth between reading and sending
  8003. packets), but also tends to make the underlying transport use itself
  8004. more efficiently (e.g. by defeating the Nagle algorithm and/or Delayed
  8005. ACK stratagem of the TCP layer). Furthermore, it allows transfers to
  8006. work smoothly on extremely slow network congestions that would
  8007. otherwise cause timeouts and retransmissions, and even failure when the
  8008. retry limit was exceeded.
  8009. The trick is knowing when we can stream:
  8010. 1. If C-Kermit has opened a TCP socket or X.25 connection, it offers
  8011. stream.
  8012. 2. If C-Kermit has been started with the -I (uppercase) option, or if
  8013. it has been told to SET RELIABLE ON, it offers to stream.
  8014. 3. If C-Kermit is in remote mode, and has been told to SET RELIABLE
  8015. AUTO (or ON), it always offers to stream, and also always agrees to
  8016. stream, if the other Kermit offers. Unless you take explicit
  8017. actions to override the defaults, this allows the local Kermit (the
  8018. one that made the connection, and so knows whether it's reliable)
  8019. to control streaming.
  8020. (Note that an offer to stream also results in a Clear-Channel
  8021. announcement if CLEAR-CHANNEL is set to AUTO; see Section 4.19.)
  8022. When BOTH Kermits offer to stream, then they stream; otherwise they
  8023. don't. Thus streaming-capable Kermit programs interoperate
  8024. automatically and transparently with nonstreaming ones. If the two
  8025. Kermits do agree to stream, you'll see the word "STREAMING" on the
  8026. fullscreen file-transfer display in the Window Slots field. You can
  8027. also find out afterwards with the STATISTICS or SHOW STREAMING
  8028. commands.
  8029. WARNING: Automatic choice of streaming is based on the assumption of
  8030. a "direct" end-to-end network connection; for example, a Telnet or
  8031. Rlogin connection from host A to host B, and transferring files
  8032. between A and B. However, if your connection has additional
  8033. components -- something "in the middle" (B) that you have made a
  8034. network connection to, which makes a separate connection to the
  8035. destination host (C), then you don't really have a reliable
  8036. connection, but C-Kermit has no way of knowing this; transferring
  8037. files between A and C will probably fail. In such cases, you'll need
  8038. to tell the *local* C-Kermit to "set reliable off" before
  8039. transferring files (it does no good to give this command to the
  8040. remote Kermit since the local one controls the RELIABLE setting).
  8041. Streaming is like using an infinite window size, with no timeouts and
  8042. no tolerance for transmission errors (since there shouldn't be any). It
  8043. relies on the underlying transport for flow control, error correction,
  8044. timeouts, and retransmission. Thus it is very suitable for use on
  8045. TCP/IP connections, especially slow or bursty ones, since Kermit's
  8046. packet timeouts won't interfere with the transfer -- each packet takes
  8047. as long to reach its destination as it takes TCP to deliver it. If TCP
  8048. can't deliver the packet within its own timeout period (over which
  8049. Kermit has no control), it signals a fatal error. Just like FTP.
  8050. Streaming goes much faster than non-streaming when a relatively small
  8051. packet length is used, and it tends to go faster than non-streaming
  8052. with even the longest packet lengths. The Kermit window size is
  8053. irrelevant to streaming protocol, but still might affect performance in
  8054. small ways since it can result in different paths through the code.
  8055. The definition of "reliable transport" does not necessarily demand
  8056. 8-bit and control-character transparency. Streaming can work with
  8057. parity and/or control-character prefixing just as well (but not as
  8058. fast) as without them; in such cases you can leave RELIABLE set to ON,
  8059. but set CLEARCHANNEL and/or PARITY appropriately.
  8060. Maximum performance -- comparable to and often exceeding FTP -- is
  8061. achieved on socket-to-socket connections (in which the considerable
  8062. overhead of the terminal driver and Telnet or Rlogin server is
  8063. eliminated) with long packets and the new "brief" file-transfer display
  8064. ( Section 4.16).
  8065. 4.20.1. Commands for Streaming
  8066. SET RELIABLE { ON, OFF, AUTO }
  8067. SET RELIABLE ON tells Kermit that it has a reliable transport.
  8068. SET RELIABLE OFF tells Kermit the transport is not reliable.
  8069. SET RELIABLE AUTO tells Kermit that it should SET RELIABLE ON
  8070. whenever it makes a reliable connection (e.g. TELNET or SET HOST
  8071. on a TCP/IP or X.25 network), and when in remote mode it should
  8072. believe the transport is reliable if the other Kermit says it is
  8073. during Kermit protocol negotiation.
  8074. AUTO is the default; the Kermit program that makes the connection knows
  8075. whether it is reliable, and tells the remote Kermit.
  8076. The RELIABLE setting has several effects, including:
  8077. * It can affect the timeouts used during normal ACK/NAK protocol.
  8078. * It can affect the clear-channel announcement.
  8079. * It can affect streaming.
  8080. If you TELNET or SET HOST somewhere, this includes an implicit SET
  8081. RELIABLE ON command. The -I command-line option is equivalent to SET
  8082. RELIABLE ON.
  8083. Since SET RELIABLE ON (and -I) also implies SET CLEAR CHANNEL ON, you
  8084. might find that in certain cases you need to tell Kermit that even
  8085. though the connection is reliable, it doesn't have a clear channel
  8086. after all:
  8087. SET CLEAR-CHANNEL OFF
  8088. SET PREFIXING CAUTIOUS ; or whatever...
  8089. You can control streaming without affecting the other items with:
  8090. SET STREAMING { ON, OFF, AUTO }
  8091. AUTO is the default, meaning streaming will occur if Kermit has made a
  8092. TCP/IP connection or if RELIABLE is ON (or it was started with the -I
  8093. command line option). OFF means don't stream; ON means offer to stream
  8094. no matter what.
  8095. 4.20.2. Examples of Streaming
  8096. Here we look at the use and behavior of streaming on several different
  8097. kinds of connections, and compare its performance with non-streaming
  8098. transfers.
  8099. 4.20.2.1. Streaming on Socket-to-Socket Connections
  8100. Here we get streaming automatically when both Kermit programs are
  8101. capable of it, since they both make socket connections. For example, on
  8102. the far end:
  8103. C-Kermit> set host * 3000
  8104. C-Kermit> server
  8105. and on the near end:
  8106. C-Kermit> set host foo.bar.xyz.com 3000
  8107. (now give SEND and GET command)
  8108. All subsequent file transfers use streaming automatically.
  8109. Here are the results from 84 trials, run on a production network,
  8110. disk-to-disk, in which a 1-MB binary file (the SunOS C-Kermit Sparc
  8111. executable) was sent from a Sun Sparc-10 with SunOS 4.1.3 to an IBM
  8112. Power Server 850 with AIX 4.1, socket-to-socket, over a 10Mbps 10BaseT
  8113. Ethernet, using minimal control-character unprefixing, window sizes
  8114. from 10 to 32, and packet sizes from 1450 to 9010:
  8115. Streaming Nonstreaming
  8116. Max CPS 748955 683354
  8117. Min CPS 221522 172491
  8118. Mean CPS 646134 558680
  8119. Median CPS 678043 595874
  8120. Std Dev 101424 111493
  8121. Correlations:
  8122. CPS and window size: -0.036
  8123. CPS and packet length: 0.254
  8124. CPS and streaming: 0.382
  8125. Note that the relationship between streaming and throughput is
  8126. significantly stronger than that between CPS and window size or packet
  8127. length.
  8128. Also note that this and all other performance measurements in this
  8129. section are snapshots in time; the results could be much different at
  8130. other times when the load on the systems and/or the network is higher
  8131. or lower.
  8132. In a similar socket-to-socket trial, but this time over a wide-area
  8133. TCP/IP connection (from New York City to Logan, Utah, about 2000
  8134. miles), the following results were obtained:
  8135. Streaming Nonstreaming
  8136. Max CPS 338226 318203
  8137. Min CPS 191659 132314
  8138. Mean CPS 293744 259240
  8139. Median CPS 300845 273271
  8140. Std Dev 41914 52351
  8141. Correlations:
  8142. CPS and window size: 0.164
  8143. CPS and packet length: 0.123
  8144. CPS and streaming: 0.346
  8145. 4.20.2.2. Streaming on Telnet Connections
  8146. In this case the local copy of Kermit is told to TELNET or SET HOST,
  8147. and so it knows it has a reliable connection and -- unless it has been
  8148. told not to -- will offer to stream, and the other Kermit program,
  8149. since it has STREAMING set to AUTO, agrees.
  8150. Since we have a reliable connection, we'll also get control-character
  8151. unprefixing automatically because of the new clear-channel protocol
  8152. ( Section 4.19).
  8153. Any errors that occur during streaming are fatal to the transfer. The
  8154. message is "Transmission error on reliable link". Should this happen:
  8155. 1. Check the remote Kermit's flow control setting (SHOW
  8156. COMMUNICATIONS). If it is NONE, change it to XON/XOFF, or vice
  8157. versa. If it is XON/XOFF (or you just changed it to XOFF/XOFF),
  8158. make sure the file sender is prefixing the XON and XOFF characters.
  8159. In the most drastic case, use "set prefix all" to force prefixing
  8160. of all control characters.
  8161. 2. The remote Telnet server might chop off the 8th bit. In that case,
  8162. tell C-Kermit to "set parity space". Or, you might be able to force
  8163. the Telnet to allow eight-bit data by telling C-Kermit to "set
  8164. telopt binary request accept" -- that is, request the Telnet server
  8165. to enter binary mode, and accept binary-mode bids from the server.
  8166. 3. The remote Telnet server might have a buffering limitation. If a
  8167. and b don't cure the problem, tell the file receiver to "set
  8168. receive packet-length 1000" (or other number -- use the largest one
  8169. that works). This too, is no different from the non-streaming case
  8170. (more about this in Section 4.20.2.3).
  8171. And remember you can continue interrupted binary-mode transfers where
  8172. they left off with the RESEND (= SEND /RECOVER) command.
  8173. Here are the figures for the same 84 trials between the same Sun and
  8174. IBM hosts as in 4.20.2.1, on the same network, but over a Telnet
  8175. connection rather than socket-to-socket:
  8176. Streaming Nonstreaming
  8177. Max CPS 350088 322523
  8178. Min CPS 95547 173152
  8179. Mean CPS 321372 281830
  8180. Median CPS 342604 291469
  8181. Std Dev 40503 29948
  8182. Correlations:
  8183. CPS and window size: 0.001
  8184. CPS and packet length: 0.152
  8185. CPS and streaming: 0.128
  8186. Here the effect is not as emphatic as in the socket-to-socket case, yet
  8187. on the whole streaming tends to be beneficial.
  8188. Additional measurements on HP-UX using C-Kermit 7.0 Beta.06:
  8189. Windowing Streaming
  8190. HP-UX 8->8 not tested 14Kcps
  8191. HP-UX 8->9 not tested 76Kcps
  8192. HP-UX 8->10 36Kcps 66Kcps
  8193. HP-UX 9->9 not tested 190Kcps
  8194. HP-UX 9->10 160Kcps 378Kcps
  8195. 4.20.2.3. Streaming with Limited Packet Length
  8196. The IRIX telnet server (at least the ones observed in IRIX 5.3 and 6.2)
  8197. does not allow Kermit to send packets longer than 4096 bytes. Thus when
  8198. sending from IRIX C-Kermit when it is on the remote end of a Telnet
  8199. connection, the packet length must be 4K or less. Trials in this case
  8200. (in which packet lengths range from 1450 to 4000) show a strong
  8201. advantage for streaming, which would be evident in any other case where
  8202. the packet length is restricted, and stronger the shorter the maximum
  8203. packet length.
  8204. Streaming Nonstreaming
  8205. Max CPS 426187 366870
  8206. Min CPS 407500 276517
  8207. Mean CPS 415226 339168
  8208. Median CPS 414139 343803
  8209. Std Dev 6094 25851
  8210. Correlations:
  8211. CPS and window size: 0.116
  8212. CPS and packet length: 0.241
  8213. CPS and streaming: 0.901
  8214. 4.20.2.4. Streaming on Dialup Connections
  8215. Here "dialup" refers to a "direct" dialup connection, not a SLIP or PPP
  8216. connection, which is only a particular kind of TCP/IP connection.
  8217. Attempt this at your own risk, and then only if (a) you have
  8218. error-correcting modems, and (b) the connections between the modems and
  8219. computers are also error-free, perfectly flow-controlled, and free of
  8220. interrupt conflicts. Streaming can be used effectively and to fairly
  8221. good advantage on such connections, but remember that the transfer is
  8222. fatal if even one error is detected (also remember that should a
  8223. binary-mode transfer fail, it can be recovered from the point of
  8224. failure with RESEND).
  8225. To use streaming on an unreliable connection, you must tell both
  8226. Kermits that the connection is reliable:
  8227. kermit -I
  8228. or:
  8229. C-Kermit> set reliable on
  8230. In this case, it will probably be necessary to prefix some control
  8231. characters, for example if your connection is through a terminal server
  8232. that has an escape character. Most Cisco terminal servers, for example,
  8233. require Ctrl-^ (30, as well as its high-bit equivalent, 158) to be
  8234. prefixed. To unprefix these, you'll need to defeat the "clear channel"
  8235. feature:
  8236. C-Kermit> set reliable on
  8237. C-Kermit> set clear-channel off
  8238. C-Kermit> set prefixing none
  8239. C-Kermit> set control prefix 1 13 30 158 ; and whatever else is necessary
  8240. Dialup trials were done using fixed large window and packet sizes. They
  8241. compare uploading and downloading of two common types of files, with
  8242. and without streaming. Configuration:
  8243. HP-9000/715/33 -- 57600bps, RTS/CTS -- USR Courier V.34 --
  8244. V.34+V.42, 31200bps -- USR V.34+ Rackmount -- 57600bps, RTS/CTS --
  8245. Cisco terminal server -- Solaris 2.5.1. Packet size = 8000, Window
  8246. Size = 30, Control Character Unprefixing Minimal (but including the
  8247. Cisco escape character).
  8248. Since this is not a truly reliable connection, a few trials failed when
  8249. a bad packet was received (most likely due to UART overruns); the
  8250. failure was graceful and immediate, and the message was informative.
  8251. The results of ten successful trials uploading and downloading the two
  8252. files with and without streaming are:
  8253. Streaming..
  8254. Off On
  8255. Upload 5194 5565 txt (= C source code, 78K)
  8256. 3135 3406 gz (= gzip file, compressed, 85K)
  8257. Download 5194 5565 txt
  8258. 3041 3406 gz
  8259. Each CPS figure is the mean of 10 results.
  8260. A brief test was also performed on a LAT-based dialout connection from
  8261. a VAX 3100 with VMS 5.5 to a USR Courier V.34 connected to a DECserver
  8262. 700 at 19200 bps. The 1-MB Sparc executable downloaded from a Sun to
  8263. the VAX at 1100cps without streaming and 1900cps with streaming, using
  8264. 8000-byte packets, 30 window slots, and minimal prefixing in both
  8265. cases.
  8266. 4.20.2.5. Streaming on X.25 Connections
  8267. We have only limited access to X.25 networks. One trial was performed
  8268. in which the 1MB Solaris 2.4 Sparc executable was transferred over a
  8269. SunLink X.25 connection; nothing is known about the actual physical
  8270. connection. With a packet length of 8000 and a window size of 30, the
  8271. file transferred at 6400 cps (using a maximum of 6 window slots). With
  8272. the same packet length, but with streaming, it transferred without
  8273. mishap at 6710 cps, about 5% faster.
  8274. 4.20.3. Streaming - Preliminary Conclusions
  8275. The results vary with the particular connection, but are good overall.
  8276. Although numerous lower-level tricks can be used to improve performance
  8277. on specific platforms or connection methods, streaming occurs at a
  8278. high, system-independent level of the Kermit protocol and therefore can
  8279. apply to all types of platforms and (reliable) connections
  8280. transparently.
  8281. 4.21. The TRANSMIT Command
  8282. Prior to C-Kermit 7.0, the TRANSMIT command transmitted in text or
  8283. binary mode according to SET FILE TYPE { TEXT, BINARY }. But now that
  8284. binary mode is likely to be the default for protocol transfers, it is
  8285. evident that this not also an appropriate default for TRANSMIT, since
  8286. binary-mode TRANSMIT is a rather specialized and tricky operation.
  8287. Therefore, TRANSMIT defaults to text mode always, regardless of the
  8288. FILE TYPE setting.
  8289. C-Kermit 7.0 expands the capabilities of the TRANSMIT command by adding
  8290. the following switches (see Section 1.5). The new syntax is:
  8291. TRANSMIT [ switches... ] filename
  8292. Zero or more switches may be included:
  8293. /PIPE
  8294. When /PIPE is included, "filename" is interpreted as a system
  8295. command or program whose output is to be sent. Synonym:
  8296. /COMMAND. Example:
  8297. transmit /pipe finger
  8298. You may enclose the command in braces, but you don't have to:
  8299. xmit /pipe {ls -l | sort -r +0.22 -0.32 | head}
  8300. /BINARY
  8301. Transmits the file (or pipe output) in binary mode.
  8302. /TEXT
  8303. Transmits the file (or pipe output) in line-oriented text mode.
  8304. Current FILE CHARACTER-SET and TERMINAL CHARACTER-SET selections
  8305. govern translation. Default.
  8306. /TRANSPARENT
  8307. Specifies text mode without character-set translation, no matter
  8308. what the FILE and TERMINAL CHARACTER-SET selections are.
  8309. /NOWAIT
  8310. This is equivalent to SET TRANSMIT PROMPT 0, but for this
  8311. TRANSMIT command only. Applies only to text mode; it means to
  8312. not wait for any kind of echo or turnaround character after
  8313. sending a line before sending the next line. (Normally Kermit
  8314. waits for a linefeed.)
  8315. When TRANSMIT ECHO is ON, C-Kermit tries to read back the echo of each
  8316. character that is sent. Prior to C-Kermit 7.0, 1 second was allowed for
  8317. each echo to appear; if it didn't show up in a second, the TRANSMIT
  8318. command would fail. Similarly for the TRANSMIT PROMPT character.
  8319. However, with today's congested Internet connections, etc, more time is
  8320. often needed:
  8321. SET TRANSMIT TIMEOUT number
  8322. Specifies the number of seconds to wait for an echo or the prompt
  8323. character when TRANSMIT PROMPT is nonzero; the default wait is 1
  8324. second. If you specify 0, the wait is indefinite. When a timeout
  8325. interval of 0 is specified, and a desired echo or prompt does not show
  8326. up, the TRANSMIT command will not terminate until or unless you
  8327. interrupt it with Ctrl-C; use SET TRANSMIT TIMEOUT 0 with caution.
  8328. Note: to blast a file out the communications connection without any
  8329. kind of synchronization or timeouts or other manner of checking, use:
  8330. SET TRANSMIT ECHO OFF
  8331. SET TRANSMIT PROMPT 0 (or include the /NOWAIT switch)
  8332. SET TRANSMIT PAUSE 0
  8333. TRANSMIT [ switches ] filename
  8334. In this case, text-file transmission is not-line oriented and large
  8335. blocks can be sent, resulting in a significant performance improvement
  8336. over line-at-at-time transmission. Successful operation depends (even
  8337. more than usual for the TRANSMIT command!) on a clean connection with
  8338. effective flow control.
  8339. For details on TRANSMIT and character sets, see Section 6.6.5.4.
  8340. 4.22. Coping with Faulty Kermit Implementations
  8341. Kermit protocol has been implemented in quite a few third-party
  8342. commercial, shareware, and freeware software packages, with varying
  8343. degrees of success. In most cases operation is satisfactory but slow --
  8344. only the bare minimum subset of the protocol is available -- short
  8345. packets, no sliding windows, no attributes, etc. In other cases, the
  8346. implementation is incorrect, resulting in failures at the initial
  8347. negotiation stage or corrupted files.
  8348. C-Kermit 7.0 and Kermit 95 1.1.19 include some new defense mechanisms
  8349. to help cope with the most common situations. However, bear in mind
  8350. there is only so much we can do in such cases -- the responsibility for
  8351. fixing the problem lies with the maker of the faulty software.
  8352. 4.22.1. Failure to Accept Modern Negotiation Strings
  8353. The published Kermit protocol specification states that new fields can
  8354. be added to the parameter negotiation string. These are to be ignored
  8355. by any Kermit implementation that does not understand them; this is
  8356. what makes the Kermit protocol extensible. Unfortunately, some Kermit
  8357. implementations become confused (or worse) when receiving a negotiation
  8358. string longer than the one they expect. You can try working around such
  8359. problems by telling Kermit to shorten its negotiation string (and thus
  8360. disable the corresponding new features):
  8361. SET SEND NEGOTIATION-STRING-MAX-LENGTH number
  8362. Try a number like 10. If that doesn't work, try 9, 8, 7, 6, and so on.
  8363. 4.22.2. Failure to Negotiate 8th-bit Prefixing
  8364. The published Kermit protocol specification states that 8th-bit
  8365. prefixing (which allows transfer of 8-bit data over a 7-bit connection)
  8366. occurs if the file sender puts a valid prefix character (normally "&")
  8367. in the 8th-bit-prefix field of the negotiation string, and the receiver
  8368. puts either a letter "Y" or the same prefix character. At least one
  8369. faulty Kermit implementation exists that does not accept the letter
  8370. "Y". To force C-Kermit / K-95 to reply with the other Kermit's prefix
  8371. character rather than a "Y", give the following (invisible) command:
  8372. SET Q8FLAG ON
  8373. Use SET Q8FLAG OFF to restore the normal behavior.
  8374. 4.22.3. Corrupt Files
  8375. Refer to Section 4.22.2. Some Kermit implementations mistakenly
  8376. interpret the "Y" as a prefix character. Then, whenever a letter Y
  8377. appears in the data, the Y and the character that follows it are
  8378. replaced by a garbage character. At this writing, we are not sure if
  8379. there is any solution, but try "set send negotiation-string-max-length
  8380. 6" and/or "set q8flag on".
  8381. File corruption can also occur when control characters within the file
  8382. data are sent without prefixing, as at least some are by default in
  8383. C-Kermit 7.0 and K-95. Some Kermit implementations do not handle
  8384. incoming "bare" control characters. To work around, "set prefixing
  8385. all".
  8386. 4.22.4. Spurious Cancellations
  8387. The Kermit protocol specification states that if an ACK to a Data
  8388. packet contains X in its data field, the transfer of the current file
  8389. is canceled, and if it contains a Z, the entire transfer is canceled.
  8390. At least one overzealous Kermit implementation applies this rule to
  8391. non-Data packets as well, the typical symptom being that any attempt to
  8392. transfer a file whose name begins with X or Z results in cancellation.
  8393. This is because the file receiver typically sends back the name under
  8394. which it stored the file (which might not be the same as the name it
  8395. was sent with) in the ACK to the File Header packet. This is
  8396. information only and should not cause cancellation. To work around the
  8397. problem, use:
  8398. SET F-ACK-BUG { ON, OFF }
  8399. ON tells Kermit not to send back the filename in the ACK to the file
  8400. header packet as it normally would do (OFF puts Kermit back to normal
  8401. after using ON).
  8402. A variation on the this bug occurs in an obscure Kermit program for
  8403. MUMPS: When this Kermit program sends a file called (say) FOO.BAR, it
  8404. requires that the ACK to its F packet contain exactly the same name,
  8405. FOO.BAR. However, C-Kermit likes to send back the full pathname,
  8406. causing the MUMPS Kermit to fail. SET F-ACK-BUG ON doesn't help here.
  8407. So a separate command has been added to handle this situation:
  8408. SET F-ACK-PATH { ON, OFF }
  8409. Normally it is ON (regardless of the SET SEND PATHNAMES setting). Use
  8410. SET F-ACK-PATH OFF to instruct Kermit to send back only the filename
  8411. without the path in the ACK to the F packet.
  8412. 4.22.5. Spurious Refusals
  8413. Some Kermit implementations, notably PDP-11 Kermit 3.60 and earlier,
  8414. have bugs in their handling of Attribute packets that can cause
  8415. unwarranted refusal of incoming files, e.g. based on date or size. This
  8416. can be worked around by telling one or both of the Kermit partners to:
  8417. SET ATTRIBUTES OFF
  8418. 4.22.6. Failures during the Data Transfer Phase
  8419. This can be caused by control-character unprefixing (Section
  8420. 4.22.3 ), and fixed by:
  8421. SET PREFIXING ALL
  8422. It can also have numerous other causes, explained in Chapter 10 of
  8423. Using C-Kermit: the connection is not 8-bit transparent (so use
  8424. "set parity space" or somesuch), inadequate flow control, etc. Consult
  8425. the manual.
  8426. 4.22.7. Fractured Filenames
  8427. At least one well-known PC-based communications package negotiates data
  8428. compression, which (according to the protocol specification) applies to
  8429. both the filename and the file data, but then fails to decompress the
  8430. filename. Example: C-Kermit sends a file called R000101.DAT (where
  8431. 000101 might be non-Y2K-wise YYMMDD notation), and the package in
  8432. question stores the files as R~#0101.DAT. Workaround: Tell C-Kermit to
  8433. SET REPEAT COUNTS OFF.
  8434. 4.22.8. Bad File Dates
  8435. At least one well-known PC-based communications package negotiates the
  8436. passing of file timestamps from sender to receiver, but when it is
  8437. sending files, it always gives them a timestamp of 1 February 1970.
  8438. Workaround: tell C-Kermit to SET ATTRIBUTE DATE OFF. You don't get the
  8439. file's real date, but you also don't get 1 Feb 1970; instead the file
  8440. gets the current date and time.
  8441. 4.23. File Transfer Recovery
  8442. Prior to C-Kermit 7.0, RESEND (SEND /RECOVER) and REGET (GET /RECOVER)
  8443. refused to work if FILE TYPE was not BINARY or the /BINARY switch was
  8444. not included. Now these commands include an implied /BINARY switch,
  8445. meaning they set the file type to binary for the duration of the
  8446. command automatically.
  8447. In the client/server arrangement, this also forces the server into
  8448. binary mode (if it is C-Kermit 7.0 or greater, or K95 1.1.19 or
  8449. greater) so the recovery operation proceeds, just as you asked and
  8450. expected.
  8451. BUT... Just as before, the results are correct only under the following
  8452. conditions:
  8453. * If the prior interrupted transfer was also in binary mode; or:
  8454. * If the prior transfer was in text mode and the other computer was a
  8455. "like platform" (e.g. UNIX-to-UNIX, Windows-to-Windows,
  8456. DOS-to-Windows) AND there was no character-set translation (i.e.
  8457. TRANSFER CHARACTER-SET was TRANSPARENT).
  8458. Note that these circumstances are more likely to obtain in C-Kermit
  8459. 7.0, in which:
  8460. * The default FILE TYPE in C-Kermit 7.0 is BINARY.
  8461. * The default FILE INCOMPLETE setting is AUTO, which means KEEP if
  8462. the transfer is in binary mode, DISCARD otherwise.
  8463. * C-Kermit 7.0, Kermit 95 1.1.17, and MS-DOS Kermit 3.15 and later
  8464. can recognize "like platforms" and switch into binary mode
  8465. automatically. Transfers between like platforms are always binary
  8466. unless character-set translation has been requested, and then is
  8467. still binary for all files whose names match a binary pattern,
  8468. unless the automatic mechanisms have been disabled (with a /TEXT
  8469. switch, or with SET TRANSFER MODE MANUAL).
  8470. * SEND /BINARY and GET /BINARY always force binary-mode transfers,
  8471. even when FILE TYPE is TEXT, even when TRANSFER MODE is AUTOMATIC,
  8472. even when PATTERNS are ON and the file's name matches a text
  8473. pattern.
  8474. But also note that the automatic client/server transfer-mode
  8475. adjustments do not work with versions of C-Kermit prior to 7.0 or K95
  8476. prior to 1.1.16.
  8477. If the prior transfer was in text mode:
  8478. * If text-mode transfers between the two platforms are
  8479. "length-changing" (as they are between UNIX -- which terminates
  8480. text lines with LF -- and DOS or Windows -- which terminates text
  8481. lines with CRLF), the recovered file will be corrupt.
  8482. * If text-mode transfers between the two platforms are not
  8483. length-changing, but character-set translation was active in the
  8484. prior transfer, the result will be a file in which the first part
  8485. has translated characters and the second part does not.
  8486. But in C-Kermit 7.0 and K95 1.1.19 and later, incompletely transferred
  8487. text files are not kept unless you change the default. But if you have
  8488. done this, and you have an incompletely transferred text file, you'll
  8489. need to:
  8490. * Transfer the whole file again in text mode, or:
  8491. * Use SEND /STARTING-AT: to recover the transfer at the correct
  8492. point; but you have to find out what that point is, as described in
  8493. the manual.
  8494. Kermit has no way of knowing whether the previous transfer was in text
  8495. or binary mode so it is your responsibility to choose the appropriate
  8496. recovery method.
  8497. If you use C-Kermit to maintain parallel directories on different
  8498. computers, using SET FILE COLLISION to transfer only those files that
  8499. changed since last time, and the files are big enough (or the
  8500. connection slow enough) to require SEND /RECOVER to resume interrupted
  8501. transfers, you should remember that SEND /RECOVER (RESEND) overrides
  8502. all FILE COLLISION settings. Therefore you should use SEND /RECOVER
  8503. (RESEND) only on the file that was interrupted, not the file group. For
  8504. example, if the original transfer was initiated with:
  8505. SEND *
  8506. and was interrupted, then after reestablishing your connection and
  8507. starting the Kermit receiver with SET FILE COLLISION UPDATE on the
  8508. remote end, use the following sequence at the sender to resume the
  8509. transfer:
  8510. SEND /RECOVER name-of-interrupted-file
  8511. and then:
  8512. SEND *
  8513. (In C-Kermit 7.0 and later, \v(filename) contains the name of the file
  8514. most recently transferred, as long you have not EXITed from Kermit or
  8515. changed directory, etc.
  8516. 4.24. FILE COLLISION UPDATE Clarification
  8517. In UNIX, file modification dates are used when comparing the file date
  8518. with the date in the attribute packet. In VMS, however, the file
  8519. creation date is used. These two policies reflect the preferences of
  8520. the two user communities.
  8521. Also, remember that the file date/time given in the attribute packet is
  8522. the local time at the file sender. At present, no timezone conversions
  8523. are defined in or performed by the Kermit protocol. This is primarily
  8524. because this feature was designed at a time when many of the systems
  8525. where Kermit runs had no concept of timezone, and therefore would be
  8526. unable to convert (say, to/from GMT or UTC or Zulu time).
  8527. As a consequence, some unexpected results might occur when transferring
  8528. files across timezones; e.g. commands on the target system that are
  8529. sensitive to file dates might not work (UNIX "make", backups, etc).
  8530. Timezone handling is deferred for a future release.
  8531. 4.25. Autodownload Improvements
  8532. Refer to pages 164-165 ofUsing C-Kermit about the hazards of
  8533. autodownload when C-Kermit is "in the middle". As of C-Kermit 7.0, no
  8534. more hazards. If C-Kermit has TERMINAL AUTODOWNLOAD ON and it detects a
  8535. packet of the current protocol type (Kermit or Zmodem), it "erases" the
  8536. visual aspect of the packet that would be seen by the terminal (or,
  8537. more to the point, the emulator, such as K95). This way, only C-Kermit
  8538. goes into RECEIVE mode, and not also the terminal emulator through
  8539. which C-Kermit is accessed. And therefore, it is no longer necessary to
  8540. SET TERMINAL AUTODOWNLOAD OFF to prevent multiple Kermits from going
  8541. into receive mode at once, but of course it is still necessary to
  8542. ensure that, when you have multiple Kermits in a chain, that the
  8543. desired one receives the autodownload.
  8544. The defaults have not been changed; Kermit 95 still has autodownload ON
  8545. by default, and C-Kermit has it OFF by default.
  8546. 5. CLIENT/SERVER
  8547. 5.0. Hints
  8548. If you use SET SERVER GET-PATH to set up your server, and the GET-PATH
  8549. does not include the server's current directory, clients can become
  8550. quite confused. For example, "remote dir oofa.txt" shows a file named
  8551. oofa.txt, but "get oofa.txt" fails. In this situation, you should
  8552. either DISABLE DIR or make your GET-PATH include the current directory.
  8553. 5.1. New Command-Line Options
  8554. The -G command-line option is like -g (GET), except the incoming file
  8555. is sent to standard output rather than written to disk.
  8556. The -I option ("Internet") is used to tell a remote C-Kermit program
  8557. that you are coming in via Internet Telnet or Rlogin and therefore have
  8558. a reliable connection. The -I option is equivalent to SET RELIABLE ON
  8559. and SET FLOW NONE.
  8560. The -O option ("Only One") tells C-Kermit to enter server mode but then
  8561. exit after the first client operation.
  8562. See Section 9.3 for details.
  8563. 5.2. New Client Commands
  8564. BYE and FINISH no longer try to do anything if a connection is not
  8565. active. Thus a sequence like "hangup" followed by "bye" or "finish"
  8566. will no longer get stuck in a long timeout-and-retransmission cycle,
  8567. nor will it try to open a new connection.
  8568. REMOTE EXIT
  8569. Similar to FINISH, except it ensures that the Kermit server
  8570. program exits back to the operating system or shell prompt.
  8571. (FINISH would return it to its interactive prompt if it was
  8572. started in interactive mode, and would cause it to exit if it
  8573. entered server mode via command-line option.) When C-Kermit is
  8574. to be the server, you can use { ENABLE, DISABLE } EXIT to
  8575. control the client's access to this feature.
  8576. REMOTE MKDIR directory-name
  8577. Tells the client to ask the server to create a directory with
  8578. the given name, which can be absolute or relative. The syntax of
  8579. the directory name depends on the Kermit server (seenext
  8580. section); in all cases, it can be in the syntax of the system
  8581. where the server is running (UNIX, VMS, DOS, etc) but newer
  8582. servers also accept UNIX syntax, no matter what the underlying
  8583. platform. The server will not execute this command if (a) it
  8584. does not understand it, (b) a DISABLE MKDIR command has been
  8585. given, or (c) a DISABLE CWD command has been given; otherwise,
  8586. the command is executed, but will fail if the directory can not
  8587. be created, in which cases most servers will attempt to return a
  8588. message giving the reason for failure. The REMOTE MKDIR command
  8589. succeeds if the remote directory is created, or if it already
  8590. exists and therefore does not need to be created, and fails
  8591. otherwise.
  8592. REMOTE RMDIR directory-name
  8593. Tells the client to ask the server to remove (delete) a
  8594. directory with the given name. The same considerations apply as
  8595. for REMOTE MKDIR.
  8596. REMOTE SET FILE INCOMPLETE { DISCARD, KEEP, AUTO }
  8597. Previously this was only available in its earlier form, REMOTE
  8598. SET INCOMPLETE (no FILE). The earlier form is still available,
  8599. but invisible. Also, AUTO was added, meaning KEEP if in binary
  8600. mode, DISCARD otherwise.
  8601. REMOTE SET TRANSFER MODE { AUTOMATIC, MANUAL }
  8602. Tells the client to ask the server to set the given
  8603. file-transfer mode. Automatic means (roughly): if the client and
  8604. the server are running on the same kind of computer (e.g. both
  8605. are on UNIX), then use binary mode automatically; if the system
  8606. types are different, use some other method to automatically
  8607. determine text or binary mode, such as filename pattern
  8608. matching. MANUAL means, in this context, obey the client's FILE
  8609. TYPE setting (TEXT or BINARY). Synonym: REMOTE SET XFER MODE.
  8610. [ REMOTE ] QUERY KERMIT function(args...)
  8611. Prior to C-Kermit 7.0, the arguments were not evaluated locally.
  8612. Thus it was not possible to have the server run the function
  8613. with client-side variables as arguments. Now:
  8614. define \%a oofa.*
  8615. remote query kermit files(\%a) ; Client's \%a
  8616. remote query kermit files(\\%a) ; Server's \%a
  8617. [ REMOTE ] LOGIN [ user [ password ] ]
  8618. LOGIN is now a synonym for REMOTE LOGIN.
  8619. LOGOUT
  8620. This command, when given in local mode, is equivalent to REMOTE
  8621. LOGOUT. When given at the IKSD prompt, it logs out the IKSD.
  8622. When given at the C-Kermit prompt when it has no connection, it
  8623. does nothing.
  8624. Note that in C-Kermit 7.0, the REMOTE (or R) prefix is not required for
  8625. QUERY, since there is no local QUERY command. The new top-level QUERY
  8626. command does exactly what REMOTE QUERY (RQUERY) does.
  8627. All REMOTE commands now have single-word shortcuts:
  8628. Shortcut Full Form
  8629. RASG REMOTE ASSIGN
  8630. RCD REMOTE CD
  8631. RCOPY REMOTE COPY
  8632. RDEL REMOTE DELETE
  8633. RDIR REMOTE DIRECTORY
  8634. REXIT REMOTE EXIT
  8635. RHELP REMOTE HELP
  8636. RHOST REMOTE HOST
  8637. RPWD REMOTE PWD
  8638. RSET REMOTE SET
  8639. etc.
  8640. The R prefix is not applied to LOGIN because there is already an RLOGIN
  8641. command with a different meaning. It is not applied to LOGOUT either,
  8642. since LOGOUT knows what to do in each case, and for symmetry with
  8643. LOGIN.
  8644. 5.2.1. Remote Procedure Definitions and Calls
  8645. This is nothing new, but it might not be obvious... REMOTE ASSIGN and
  8646. REMOTE QUERY may be used to achieve remote procedure execution. The
  8647. remote procedure can be defined locally or remotely.
  8648. A remote procedure call is accomplished as noted in the previous
  8649. section:
  8650. [ remote ] query kermit function-name(args...)
  8651. This invokes any function that is built in to the Kermit server, e.g.:
  8652. [ remote ] query kermit size(foo.bar)
  8653. returns the size of the remote file, foo.bar.
  8654. Now note that C-Kermit includes an \fexecute() function, allowing it to
  8655. execute any macro as if it were a built-in function. So suppose MYMACRO
  8656. is the name of a macro defined in the server. You can execute it from
  8657. the client as follows (the redundant "remote" prefix is omitted in the
  8658. remaining examples):
  8659. query kermit execute(mymacro arg1 arg2...)
  8660. The return value, if any, is the value of the RETURN command that
  8661. terminated execution of the macro, for example:
  8662. define addtwonumbers return \feval(\%1+\%2)
  8663. The client invocation would be:
  8664. query kermit execute(addtwonumbers 3 4)
  8665. 7
  8666. The result ("7" in this case) is also assigned to the client's
  8667. \v(query) variable.
  8668. To execute a remote system command or command procedure (shell script,
  8669. etc) use:
  8670. query kermit command(name args...)
  8671. Finally, suppose you want the client to send a macro to the server to
  8672. be executed on the server end. This is done as follows:
  8673. remote assign macroname definition
  8674. query kermit execute(macroname arg1 arg2...)
  8675. Quoting is required if the definition contains formal parameters.
  8676. 5.3. New Server Capabilities
  8677. 5.3.1. Creating and Removing Directories
  8678. The C-Kermit 7.0 server responds to REMOTE MKDIR and REMOTE RMDIR
  8679. commands. The directory name may be in either the native format of the
  8680. server's computer, or in UNIX format. For example, a server running on
  8681. VMS with a current directory of [IVAN] can accept commands from the
  8682. client like:
  8683. remote mkdir olga ; Makes [IVAN.OLGA] (nonspecific format)
  8684. remote mkdir .olga ; Makes [IVAN.OLGA] (VMS format without brackets)
  8685. remote mkdir olga/ ; Makes [IVAN.OLGA] (UNIX relative format)
  8686. remote mkdir /ivan/olga ; Makes [IVAN.OLGA] (UNIX absolute format)
  8687. remote mkdir [ivan.olga] ; Makes [IVAN.OLGA] (VMS absolute format)
  8688. remote mkdir [.olga] ; Makes [IVAN.OLGA] (VMS relative format)
  8689. 5.3.1.1. Creating Directories
  8690. If a directory name is given that contains more than one segment that
  8691. does not exist, the server attempts to create all the segments. For
  8692. example, if the client says:
  8693. REMOTE MKDIR letters/angry
  8694. a "letters" subdirectory is created in the server's current directory
  8695. if it does not already exist, and then an "angry" subdirectory is
  8696. created beneath it, if it does not already have one. This can repeated
  8697. to any reasonable depth:
  8698. REMOTE MKDIR a/b/c/d/e/f/g/h/i/j/k/l/m/n/o/p/q/r/s/t/u/v/w/z/y/z
  8699. 5.3.1.2. Removing Directories
  8700. When attempting to execute a REMOTE RMDIR, the server can remove only a
  8701. single directory, not an entire sequence or tree. The system service
  8702. that is called to remove the directory generally requires not only that
  8703. the server process has write delete access, but also that the directory
  8704. contain no files.
  8705. In the future, a REMOTE RMDIR /RECURSIVE command (and the accompanying
  8706. protocol) might be added. For now, use the equivalent REMOTE HOST
  8707. command(s), if any.
  8708. 5.3.2. Directory Listings
  8709. Directory listings are generated by C-Kermit itself, rather than by
  8710. running the underlying system's directory command. Some control over
  8711. the listing format can be obtained with the SET OPTIONS DIRECTORY
  8712. command ( Section 4.5.1). The following options affect listings
  8713. sent by the server: /[NO]HEADING, /[NO]DOTFILES, and /[NO]BACKUP. In
  8714. UNIX and VMS, the listing is always sorted by filename. There is, at
  8715. present, no protocol defined for the client to request listing options
  8716. of the server; this might be added in the future.
  8717. The server's directory listings are in the following format:
  8718. Protection or permissions:
  8719. In UNIX and OS-9, this is a 10-character field, left adjusted.
  8720. In VMS it is a 22-character field, left-adjusted. In each case,
  8721. the protection / permission codes are shown in the server
  8722. platform's native format. In other operating systems, this field
  8723. is not shown.
  8724. Size in bytes:
  8725. This is always a 10-character field. The file's size is shown as
  8726. a decimal number, right adjusted in the field. If the file is a
  8727. directory and its size can not be obtained, the size is shown as
  8728. "<DIR>". Two blanks follow this field.
  8729. Date:
  8730. Always in yyyy-mm-dd hh:mm:ss numeric format, and therefore 19
  8731. characters long. If the file's date/time can't be obtained,
  8732. zeros (0) are shown for all the digits. This field is followed
  8733. by two blanks.
  8734. Filename:
  8735. This field extends to the end of the line. Filenames are shown
  8736. relative to the server's current directory. In UNIX, symbolic
  8737. links are shown as they are in an "ls -l" listing as "linkname
  8738. -> filename".
  8739. In UNIX and VMS, listings are returned by the server in alphabetical
  8740. order of filename. There are presently no other sort or selection
  8741. options.
  8742. However, since these are fixed-field listings, all fields can be used
  8743. as sort keys by external sort programs. Note, in particular, that the
  8744. format used for the date allows a normal lexical on that field to
  8745. achieve the date ordering. For example, let's assume we have a UNIX
  8746. client and a UNIX server. In this case, the server's listing has the
  8747. date in columns 22-40, and thus could be sorted by the UNIX sort
  8748. program using "sort +0.22 -0.40" or in reverse order by "sort +0.22
  8749. -0.40r".
  8750. Since the UNIX client can pipe responses to REMOTE commands through
  8751. filters, any desired sorting can be accomplished this way, for example:
  8752. C-Kermit> remote directory | sort +0.22 -0.40
  8753. You can also sort by size:
  8754. C-Kermit> remote directory | sort +0.11 -0.19
  8755. You can use sort options to select reverse or ascending order. "man
  8756. sort" (in UNIX) for more information. And of course, you can pipe these
  8757. listings through any other filter of your choice, such as grep to skip
  8758. unwanted lines.
  8759. 5.4. Syntax for Remote Filenames with Embedded Spaces
  8760. C-Kermit and K95, when in server mode, assume that any spaces in the
  8761. file specification in an incoming GET command are filename separators.
  8762. Thus if the client gives a command like:
  8763. get {oofa.txt oofa.bin}
  8764. or, equivalently:
  8765. mget oofa.txt oofa.bin
  8766. the server tries to send the two files, oofa.txt and oofa.bin. But what
  8767. if you want the server to send you a file named, say:
  8768. D:\HP OfficeJet 500\Images\My Pretty Picture Dot PCL
  8769. How does the server know this is supposed to be one file and not seven?
  8770. In this case, you need to the send file name to the server enclosed in
  8771. either curly braces:
  8772. {D:\HP OfficeJet 500\Images\My Pretty Picture Dot PCL}
  8773. or ASCII doublequotes:
  8774. "D:\HP OfficeJet 500\Images\My Pretty Picture Dot PCL"
  8775. The method for doing this depends on your client. If your client is
  8776. C-Kermit 7.0, any recent version of Kermit 95, or MS-DOS Kermit 3.16,
  8777. then you have to enclose the name in braces just so the client can
  8778. parse it, so to send braces or doublequotes to the server, you must put
  8779. them inside the first, outside pair of braces. And you also need to
  8780. double the backslashes to prevent them from being interpreted:
  8781. get {{D:\\HP OfficeJet 500\\Images\\My Pretty Picture Dot PCL}}
  8782. get {"D:\\HP OfficeJet 500\\Images\\My Pretty Picture Dot PCL"}
  8783. To get around the requirement to double backslashes in literal
  8784. filenames, of course you can also use:
  8785. set command quoting off
  8786. get {{D:\HP OfficeJet 500\Images\My Pretty Picture Dot PCL}}
  8787. get {"D:\HP OfficeJet 500\Images\My Pretty Picture Dot PCL"}
  8788. set command quoting on
  8789. If you are giving a "kermit" command to the UNIX shell, you have to
  8790. observe the shell's quoting rules, something like this:
  8791. kermit -ig "{D:\HP OfficeJet 500\Images\My Pretty Picture Dot PCL}"
  8792. Here, the quotes go on the outside so UNIX will pass the entire
  8793. filename, spaces, braces, and all, as a single argument to Kermit, and
  8794. the backslashes are not doubled because (a) the UNIX shell ignores them
  8795. since they are in a quoted string, and (b) Kermit ignores them since
  8796. the interactive command parser is not activated in this case.
  8797. 5.5. Automatic Orientation Messages upon Directory Change
  8798. C-Kermit 7.0, when acting as a server, can send an orientation message
  8799. to the client whenever the server directory changes. For example, when
  8800. the client gives a REMOTE CD command, the server sends the contents of
  8801. the new directory's "Read Me" file to the client's screen. The
  8802. following commands govern this feature:
  8803. SET SERVER CD-MESSAGE FILE name
  8804. Given to the servr, allows the message-file name to be specified
  8805. at runtime. A list of names to look for can be given in the
  8806. following format:
  8807. {{name1}{name2}{name3}{...}}
  8808. e.g. SET SERVER CD-MESSAGE FILE
  8809. {{./.readme}{README.TXT}{READ.ME}}
  8810. REMOTE SET SERVER CD-MESSAGE { ON, OFF }
  8811. Given to the client, lets the client control whether the server
  8812. sends automatic CD messages.
  8813. SHOW SERVER
  8814. Given to server, includes CD-Message status.
  8815. The default CD message file name is system dependent. SHOW CD or SHOW
  8816. SERVER displays the list. Also see Section 4.5.2.
  8817. 5.6. New Server Controls
  8818. DISABLE ENABLE
  8819. Allows the server to configured such that DISABLEd features can
  8820. not be re-enabled by any means -- e.g. if the client is somehow
  8821. able to get the server into command mode. Once DISABLEd, ENABLE
  8822. can not be re-ENABLEd.
  8823. SET SERVER IDLE-TIMEOUT seconds
  8824. This was available previously in Kermit 95 only. Now it can be
  8825. used in C-Kermit also to specify a maximum number of seconds the
  8826. server is allowed to be idle before exiting server mode. 0
  8827. seconds means no idle timeout. In C-Kermit (but not K-95), SET
  8828. SERVER TIMEOUT and SET SERVER IDLE-TIMEOUT are mutually
  8829. exclusive -- you can have one or the other (or neither), but not
  8830. both. (Server timeouts are for the benefit of primitive Kermit
  8831. clients that are not capable of timing out on their own; to our
  8832. knowledge, no such clients are still in circulation.)
  8833. SET SERVER KEEPALIVE { ON, OFF }
  8834. (See next section).
  8835. 5.7. Timeouts during REMOTE HOST Command Execution
  8836. Prior to C-Kermit 7.0, the C-Kermit server would block waiting for
  8837. output from a system command invoked via REMOTE HOST from the client.
  8838. If the system command took a long time to execute, the client would
  8839. time out and send NAK packets. If the command took too long, the client
  8840. would reach its retry limit and give up. Even if it didn't, the NAKs
  8841. would cause unnecessary retransmissions.
  8842. In version 7.0, the C-Kermit server (VMS and select()-capable UNIX
  8843. versions only), sends "keepalive packets" (empty data packets) once per
  8844. second while waiting for the system command to complete. This procedure
  8845. should be entirely transparent to the Kermit client, and should prevent
  8846. the unwanted timeouts and NAKs. When C-Kermit 7.0 itself (or K95
  8847. 1.1.19) is the client, it prints dots to show the keepalive packets.
  8848. The keepalive feature can be turned off and on with:
  8849. SET SERVER KEEPALIVE { ON, OFF }
  8850. Normally it should be on. Turn it off it if causes trouble with the
  8851. client, or if it seems to slow down the server (as it might on some
  8852. platforms under certain circumstances).
  8853. 6. INTERNATIONAL CHARACTER SETS
  8854. Support for several new single-byte character sets was added in
  8855. C-Kermit 7.0. Unicode / ISO 10646 is not yet supported, but is a high
  8856. priority for forthcoming releases.
  8857. 6.0. ISO 8859-15 Latin Alphabet 9
  8858. To accommodate the Euro currency symbol, and to correct several other
  8859. longstanding problems with ISO Latin Alphabet 1, ISO 8859-15 Latin
  8860. Alphabet 9 was issued in May 1998. It is supported by C-Kermit 7.0 as a
  8861. transfer character set, a file character set, and a terminal character
  8862. set. Translations that preserve the new characters are available
  8863. between Latin-9 and several other sets including:
  8864. PC Code Page 858 (Western European languages, similar to CP850)
  8865. Windows Code Page 1252 (Western European languages, similar to Latin-1)
  8866. Windows Code Page 1250 (Eastern European languages, similar to Latin-2)
  8867. The Latin-9 transfer character set also allows for the OE digraph
  8868. character, used primarily in French, to be preserved in transfers
  8869. involving the DEC MCS or NeXT character sets.
  8870. The Euro character is also present in the Universal Character Set,
  8871. described in Section 6.6.
  8872. 6.1. The HP-Roman8 Character Set
  8873. The HP-Roman8 character set is supported in C-Kermit 6.0 and later but
  8874. was omitted from Table VII-4 in the 2nd Edition of Using C-Kermit due
  8875. to lack of space. It is listed inAppendix III.
  8876. 6.2. Greek Character Sets
  8877. Greek character sets were added in 6.1:
  8878. SET FILE CHARACTER-SET { CP869, ELOT927, GREEK-ISO }
  8879. SET TRANSFER CHARACTER-SET { GREEK-ISO }
  8880. GREEK-ISO is ISO 8859-7, which the same as ELOT 928.
  8881. The new Greek character sets are listed inAppendix III.
  8882. 6.3. Additional Latin-2 Character Sets
  8883. The following have been added as FILE and TERMINAL CHARACTER-SETs:
  8884. MAZOVIA-PC
  8885. A PC code page used in Poland, equivalent to CP437, but with 18
  8886. substitutions needed for Polish.
  8887. CP1250
  8888. The Windows Latin 2 Code Page. Equivalent to ISO 8859-2, but
  8889. with different encoding.
  8890. 6.4. Additional Cyrillic Character Sets
  8891. The following have been added as FILE and TERMINAL CHARACTER-SETs:
  8892. BULGARIA-PC
  8893. This is the Cyrillic PC code page used in Bulgaria, where it is
  8894. called Code Page 856. It is attributed to a company called
  8895. DATEC, Inc, but CP856 is not a proper designation, since it
  8896. refers to a Hebrew Code Page (see the IBM Registry).
  8897. CP855
  8898. This PC Code Page contains all the Cyrillic letters that are
  8899. also in ISO 8859-5, and is therefore useful for non-Russian
  8900. Cyrillic text (Ukrainian, Belarusian, etc), unlike CP866, which
  8901. has a smaller repertoire of Cyrillic letters.
  8902. CP1251
  8903. The Windows Cyrillic Code Page. Equivalent to CP855, but with
  8904. different encoding.
  8905. KOI8R
  8906. An extension to "Old KOI-8" that adds upper and lower case
  8907. Cyrillic letter Io (looks like Roman E with diaeresis) plus a
  8908. selection of box-drawing characters to columns 8 through 11,
  8909. which are vacant in original Old KOI-8. KOI8-R is used for the
  8910. Russian language. It is specified inRFC 1489.
  8911. KOI8U
  8912. A similar extension of Old KOI-8, but for Ukrainian. It is
  8913. specified inRFC 2319.
  8914. 6.5. Automatic Character-Set Switching
  8915. Prior to version 7.0, C-Kermit's file character-set always had to be
  8916. set explicitly. In 7.0 and later, it is set automatically when:
  8917. 1. This feature is enabled (as it is unless you disable it).
  8918. 2. An incoming text-mode transfer includes a transfer-character-set
  8919. announcer and you have not previously given a SET FILE
  8920. CHARACTER-SET command. In this case, C-Kermit switches to an
  8921. appropriate file character set. For example, on an HP-UX
  8922. workstation, an incoming Latin-1 file automatically selects
  8923. HP-Roman8 for the local copy of the file; in Data General AOS/VS,
  8924. it would select DG International.
  8925. 3. You give a SET TRANSFER CHARACTER-SET command without having
  8926. previously specified a FILE CHARACTER-SET. An appropriate file
  8927. character-set is chosen automatically.
  8928. In addition, when you give a SET FILE CHARACTER-SET command, the
  8929. appropriate transfer character-set is automatically chosen, to be used
  8930. when you are sending files (but this does not override the one
  8931. announced by the sender when you are receiving files).
  8932. You might not agree about what is "appropriate", so of course you can
  8933. disable or change all of the above actions.
  8934. You can disable (or re-enable) the new automatic character-set
  8935. switching feature in each direction separately:
  8936. SET RECEIVE CHARACTER-SET-SELECTION { AUTOMATIC, MANUAL }
  8937. AUTOMATIC is the default, causing the behavior described above
  8938. when an incoming file arrives. Choose MANUAL to defeat this
  8939. behavior and force your current FILE CHARACTER-SET setting to be
  8940. used, no matter what it is. Note that SET RECEIVE CHARACTER-SET
  8941. MANUAL does not disable recognition of the incoming transfer
  8942. character-set announcer, and translation from the corresponding
  8943. character-set to your current file character-set. To disable
  8944. that, use SET ATTRIBUTE CHARACTER-SET OFF.
  8945. SET SEND CHARACTER-SET-SELECTION { AUTOMATIC, MANUAL }
  8946. Again AUTOMATIC is the default, causing the behavior described
  8947. above when you give a SET { FILE, TRANSFER } CHARACTER-SET
  8948. command. Use MANUAL to allow you to specify the transfer and
  8949. file character-sets independently.
  8950. SHOW CHARACTER-SETS
  8951. Tells settings of { SEND, RECEIVE } CHARACTER-SET-SELECTION.
  8952. Normally, however, it is more convenient to leave automatic switching
  8953. active, and change any associations that are not appropriate for your
  8954. application, area, or country. The commands are:
  8955. SHOW ASSOCIATIONS
  8956. This command lists all the associations in each direction: for
  8957. each possible transfer character-set, it lists the associated
  8958. file character-set, and vice versa. These are two separate and
  8959. independent lists.
  8960. ASSOCIATE TRANSFER-CHARACTER-SET name1 [ name2 ]
  8961. Changes the association for the transfer character-set name1 to
  8962. be the file character-set name2. If name2 is omitted, automatic
  8963. switching is disabled for this transfer character-set only.
  8964. ASSOCIATE FILE-CHARACTER-SET name1 [ name2 ]
  8965. Changes the association for the file character-set name1 to be
  8966. the transfer character-set name2. If name2 is omitted, automatic
  8967. switching is disabled for this file character-set only.
  8968. 6.6. UNICODE
  8969. C-Kermit 7.0 adds support for Unicode, the Universal Character Set,
  8970. for:
  8971. * File Transfer (SEND, RECEIVE, GET, etc)
  8972. * Terminal connection (CONNECT)
  8973. * Unguarded file capture (LOG SESSION)
  8974. * Unguarded file transmission (TRANSMIT)
  8975. * Local file character-set conversion (TRANSLATE)
  8976. C-Kermit is not, however, a "Unicode application" in the sense that its
  8977. commands, messages, or user interface are Unicode. Rather, it is
  8978. "Unicode aware" in its ability to handle and convert Unicode text in
  8979. the course of file transfer and terminal connection, and you can also
  8980. use Kermit to convert local files between Unicode and other character
  8981. sets. TLA's:
  8982. BMP - Base Multilingual Plane
  8983. BOM - Byte Order Mark
  8984. CJK - Chinese, Japanese, and Korean
  8985. ISO - International Standards Organization
  8986. TLA - Three-Letter Acronym
  8987. UCS - Universal Character Set
  8988. UTF - UCS Transformation Format
  8989. Unicode and ISO 10646 are the coordinated and compatible corporate and
  8990. international standards for the Universal Character Set (UCS). Unlike
  8991. single-byte and even most multibyte character sets, the UCS can
  8992. represent all characters in every existing writing system. A flat
  8993. plain-text file encoded in some form of UCS can contain any mixture of
  8994. English, Spanish, Italian, German, Hebrew, Arabic, Greek, Russian,
  8995. Armenian, Georgian, Japanese, Chinese, Korean, Vietnamese, Tibetan,
  8996. Hindi, Bengali, Tamil, Thai, Ethiopic, and so on, plus scientific and
  8997. mathematical notation, as well as texts in Runes, Ogham, Glagolitic,
  8998. and other historic scripts.
  8999. The UCS already covers these scripts and many more, but it's an
  9000. evolving standard with efforts underway to accommodate even more
  9001. languages and writing systems. Support is growing for native UCS use on
  9002. many platforms and in many applications. The goal of the framers of the
  9003. UCS is for it to replace ASCII, the ISO Latin Alphabets, ISCII, VISCII,
  9004. the Chinese, Japanese, and Korean (CJK) multibyte sets, etc, as well as
  9005. the many private character sets in use today, in other words to become
  9006. *the* Universal Character Set.
  9007. Until that time, however, conversions between existing sets and the UCS
  9008. will be necessary when moving text between platforms and applications.
  9009. Now Kermit can help.
  9010. 6.6.1. Overview of Unicode
  9011. For a more complete picture, please visit:
  9012. http://www.unicode.org/
  9013. and access the various online introductions, FAQs, technical reports,
  9014. and other information. For greater depth, order the latest version of
  9015. the published Unicode Standard. The following overview contains a great
  9016. many oversimplifications and perhaps an opinion or two.
  9017. At present, the UCS is a 16-bit (2-byte) character set, but with
  9018. provisions to grow to a 4-byte set. UCS-2 refers to the two-byte set,
  9019. also called the Base Multilingual Plane (BMP), in which each character
  9020. has 16 bits, and therefore there are 2^16 = 65536 possible characters.
  9021. The first 128 characters are the same as US ASCII (C0 control
  9022. characters and DEL included), the next 32 are the C1 control characters
  9023. of ISO 6429, and the next 96 are the Right Half of ISO 8859-1 Latin
  9024. Alphabet 1. The remaining tens of thousands of characters are arranged
  9025. newly for the UCS, usually (but not always) in sections corresponding
  9026. to existing standards, such as ISO Latin/Cyrillic, often plus
  9027. additional characters not appearing in the existing standards due to
  9028. lack of space (or other reasons).
  9029. ISO 10646 allows for additional planes, e.g. for Egyptian hieroglyphics
  9030. or ancient (or other esoteric) CJK characters, but these planes are not
  9031. yet defined and so we will say nothing more about them here, except
  9032. that their use will require the 4-byte form of UCS, called UCS-4, in
  9033. some form (more about "forms" in Section 6.6.2).
  9034. Unicode and ISO 10646 are constantly under revision, mainly to add new
  9035. characters. The Unicode revision is denoted by a version number, such
  9036. as 1.0, 1.1, 2.0, 3.0. The ISO 10646 standard revision is identified by
  9037. Edition (such as ISO 10646-1 1993), plus reference to any amendments.
  9038. The first versions of these standards included encodings for Korean
  9039. Hangul syllables (Jamos); these encodings were changed in version 1.1
  9040. of Unicode and by Amendment 5 to ISO 10646-1. The Unicode Technical
  9041. Committee and the ISO acknowledge that this was a bad thing to do, and
  9042. promise never change encodings or character names again, since this
  9043. poses serious problems for conformance and data interchange.
  9044. A UCS-2 value is customarily written like this:
  9045. U+xxxx
  9046. where "xxxx" represents four hexadecimal digits, 0-9 and A-F. For
  9047. example, U+0041 is "A", U+00C1 is A-acute, U+042F is uppercase Cyrillic
  9048. "Ya", U+FB4F is Hebrew Ligature Alef Lamed, and U+FFFD is the special
  9049. character that means "not a character".
  9050. Most characters from widely-used alphabetic writing systems such as the
  9051. West European ones, Cyrillic, Greek, Hebrew, Vietnamese, etc, are
  9052. available in "precomposed" form; for example Uppercase Latin Letter A
  9053. with Acute Accent is a single character (as it is in Latin-1). However,
  9054. the UCS also permits composition of a base character with one or more
  9055. nonspacing diacritics. This means the same character can be represented
  9056. in more than one way, which can present problems in many application
  9057. areas, including transfer and character-set conversion of text.
  9058. Conversion from ASCII or Latin-1 to UCS-2 text is "trivial": simply
  9059. insert a NUL (0) byte before each ASCII or Latin-1 byte. Converting in
  9060. the reverse direction (provided the UCS-2 file contains only U+0000 to
  9061. U+00FF) is equally simple (if we ignore the issue of composition):
  9062. remove every second (NUL) byte. Conversion of other character sets to
  9063. and from UCS, however, requires tables or algorithms specific to each
  9064. set. Nevertheless, the relatively transparent upwards compatibility
  9065. from ASCII and Latin-1, in which a very large share of the world's
  9066. textual data is encoded, gives the UCS an entree onto existing
  9067. platforms.
  9068. But the 2-byte format and the preponderance of NUL and other control
  9069. bytes in UCS-2 text pose problems for current applications and
  9070. transmission methods. And to make matters worse, different hardware
  9071. platforms store UCS-2 characters in different byte order. Thus a UCS-2
  9072. file transferred by FTP (or accessed via NFS, etc) between two
  9073. computers with different architecture might have its bytes in the wrong
  9074. order (or worse; see Section 6.6.5.1 ).
  9075. 6.6.2. UCS Byte Order
  9076. Consider the number 1. In an 8-bit byte, this would be represented by
  9077. the following series of 0- and 1-bits:
  9078. +-----------------+
  9079. | 0 0 0 0 0 0 0 1 |
  9080. +-----------------+
  9081. Therefore in a 16-bit "word" the representation might be:
  9082. +-----------------+-----------------+
  9083. | 0 0 0 0 0 0 0 0 | 0 0 0 0 0 0 0 1 |
  9084. +-----------------+-----------------+
  9085. Now consider the number 256, which is 2 to the 8th power. The binary
  9086. representation is 100000000 (1 followed by 8 zeros). 256 would go into
  9087. a 16-bit word like this:
  9088. +-----------------+-----------------+
  9089. | 0 0 0 0 0 0 0 1 | 0 0 0 0 0 0 0 0 |
  9090. +-----------------+-----------------+
  9091. When a computer works this way, it is said to be Big Endian, meaning it
  9092. puts the most significant (biggest) byte first (on the "left") in a
  9093. 16-bit word, and the least significant byte second (on the right).
  9094. However, some other computers have the opposite arrangement, called
  9095. Little Endian, in which 1 is:
  9096. +-----------------+-----------------+
  9097. | 0 0 0 0 0 0 0 1 | 0 0 0 0 0 0 0 0 |
  9098. +-----------------+-----------------+
  9099. and 256 is:
  9100. +-----------------+-----------------+
  9101. | 0 0 0 0 0 0 0 0 | 0 0 0 0 0 0 0 1 |
  9102. +-----------------+-----------------+
  9103. Computers such as Sparc, MIPS, PA-RISC, and PowerPC are Big Endian,
  9104. whereas the PC and the Alpha are Little Endian. Endianness has never
  9105. been an issue with 7- or 8-bit characters, but it is with UCS
  9106. characters. It can be a tricky business to share or transfer a UCS-2
  9107. file between two different kinds of computers.
  9108. To alleviate (but not entirely solve) the problem, UCS-2 files are
  9109. supposed to begin with the Unicode character U+FEFF, Zero-Width
  9110. No-Break Space (ZWNBS). This is a kind of "no-op" (note: any such
  9111. assertion must normally be qualified with many "but ifs" and "excepts"
  9112. which are omitted here in the interest of brevity). If the bytes are
  9113. reversed the ZWNBS becomes U+FFFE, which is not (and never will be) a
  9114. defined UCS character. U+FEFF at the beginning of a UCS file is
  9115. therefore called a Byte Order Mark, or BOM.
  9116. Any application that creates a UCS-2 (or UTF-16, or UCS-4) file should
  9117. include a BOM, and any application that reads one should test for a
  9118. BOM, and if one is found, infer the byte order from it. This is a
  9119. convention, however -- not a standard or a requirement -- and
  9120. applications vary in their ability to handle BOMs and "backwards" UCS-2
  9121. files.
  9122. Note that a BOM is useful only at the beginning of a file. If you
  9123. append one UCS-2 file to another, and both have BOMs, the internal BOM
  9124. is no longer a BOM. And if the byte orders of the two files differ,
  9125. then either the first part or the second will be backwards. (Various
  9126. other undesirable effects might also occur, not discussed here.)
  9127. 6.6.2. UCS Transformation Formats
  9128. UCS textual data can be modified in various ways for transmission or
  9129. storage. Any officially sanctioned method of doing this is called a UCS
  9130. Transformation Format, or UTF. One such method, called UTF-16, is
  9131. essentially identical with UCS-2 except that it designates certain code
  9132. values as "escape sequences" (called surrogate pairs) to access
  9133. characters in other planes without having to use full UCS-4. We won't
  9134. discuss UTF-16 further here, since at the moment there are no other
  9135. planes. Several other UTF's (such as UTF-1, UTF-2, and UTF-7) have
  9136. fallen into disuse and are not discussed here. The most important
  9137. transformation format today is UTF-8.
  9138. UTF-8, so called because it "serializes" UCS-2 data into a stream of
  9139. 8-bit bytes, is designed to allow the UCS to work with present-day
  9140. communications gear, computers, and software. The most important
  9141. properties of UTF-8 are that byte order is constant (no byte swapping)
  9142. and all (7-bit) ASCII characters represent themselves. Therefore
  9143. conversion between ASCII and UTF-8 is no conversion at all, and
  9144. applications or platforms (such as Plan 9 from Bell Labs) that use
  9145. UTF-8 "for everything" can still run traditional ASCII-only
  9146. applications and be accessed from them. In particular, unlike UCS-2,
  9147. ASCII characters are not padded with NUL bytes. But also unlike UCS-2,
  9148. there is no transparency for Latin-1 or any other non-ASCII character
  9149. set. Every non-ASCII UCS-2 character is represented by a sequence of 2
  9150. or 3 UTF-8 bytes. Thus UTF-8 is more compact than UCS-2 for text
  9151. containing a preponderance of ABC's (or other ASCII characters), about
  9152. the same as UCS-2 for other alphabetic scripts (Cyrillic, Roman, Greek,
  9153. etc), and larger than UCS-2 for Chinese, Japanese, and Korean.
  9154. The UTF-8 uncoding of the UCS has been adopted by the Internet as the
  9155. preferred character set for new applications, and is gradually being
  9156. retrofitted into traditional applications like FTP ([550]RFC 2640).
  9157. 6.6.3. Conformance Levels
  9158. Although the Unicode and ISO 10646 standards both describe the same
  9159. character set, these standards differ in many ways, including their
  9160. stated requirements for conformance and their classification of
  9161. conformance levels.
  9162. Kermit has always abided by ISO character-set standards, including ISO
  9163. character-set designation and invocation methods. In adapting Unicode,
  9164. therefore, we had to choose from among the available ISO designations
  9165. which, in turn, correspond with ISO 10646 conformance levels. At
  9166. present, Kermit claims the lowest conformance level, 1, meaning
  9167. (roughly) that it does not handle combining forms and it does not
  9168. handle Korean Hangul Jamos (just as, at present, it does not handle
  9169. Korean in general). Note that ISO 10646 Conformance Levels 1 and 2
  9170. sidestep the issue of the code changes for Korean Hangul by announcing
  9171. non-support for Hangul regardless of encoding.
  9172. ISO 10646 Conformance Level 1 is approximately equivalent to Unicode
  9173. Normalization Form C (described in Unicode Technical Report 15,
  9174. incorporated into Unicode 3.0).
  9175. As noted in Section 6.6.2, Kermit does not claim to support UTF-16
  9176. at the present time, hence the UCS-2 nomenclature. Kermit treats
  9177. surrogates just as if they were any other UCS-2 characters, rather than
  9178. as escapes to other planes, which means that (except when converting
  9179. between UCS-2 and UTF-8) they are translated to "error" characters,
  9180. since (a) no other planes are defined yet (and if they were, no other
  9181. character sets supported by Kermit would encode their characters), and
  9182. (b) no valid surrogate character corresponds to any other UCS-2
  9183. character.
  9184. A minor yet significant aspect of Unicode 3.0 and some recent
  9185. perturbation of ISO 10646-1 (probably Amendment 18, "Symbols and Other
  9186. Characters") is the addition of the Euro Sign at U+20AC. As noted in
  9187. Section 6.0, Kermit's "Euro compliance" includes conversion
  9188. between Latin Alphabet 9 and various PC code pages. Text can also be
  9189. converted between UCS-2 or UTF-8 and any other Euro-compliant character
  9190. set (Latin-9, CP858, CP1250, CP1252) without loss of the Euro Sign.
  9191. 6.6.4. Relationship of Unicode with Kermit's Other Character Sets
  9192. Kermit's character sets are divided into two groups: single-byte sets
  9193. (such as Roman, Hebrew, Cyrillic, Greek) and multibyte (various
  9194. Japanese sets). The two groups are distinct since one normally would
  9195. not expect to convert Kanji ideograms to Roman (or other) letters, or
  9196. vice versa.
  9197. Unicode character-set conversion works with both groups, but obviously
  9198. the result depends on the repertoires of the source and destination
  9199. character-sets both including the characters in the file. For example,
  9200. you can translate a Hungarian text file between Latin-2 and Unicode,
  9201. but not between (say) Unicode and Latin/Greek. By the same token you
  9202. can convert Japanese text from Shift-JIS or EUC or JIS-7 to Unicode and
  9203. back, but you can't convert the same file to (say) Latin-1 if it
  9204. contains Japanese characters.
  9205. JIS-7 is equivalent to DEC Kanji and ISO-2022-JP except that the
  9206. latter two do not support halfwidth Katakana. Kermit treats all
  9207. three of these sets the same way, i.e. as JIS-7.
  9208. As noted, Kermit presently does not handle combining diacritics, and so
  9209. will not correctly convert UCS files that use them into a single-byte
  9210. character set. For example, if a UCS file contains Latin Capital Letter
  9211. A (U+0041) followed by Combining Acute Accent (U+0301), the result will
  9212. be a two-character sequence, A followed by another character. This is
  9213. what is meant by Conformance Level 1. (The situation grows worse with
  9214. multiple diacritics, since they can occur in any order.)
  9215. A higher level of conformance is possible, in which "canonical
  9216. equivalences" are handled via algorithms and databases, at some
  9217. (perhaps considerable) cost in performance, since a fair amount of
  9218. additional code must be executed for every character during data
  9219. transfer (database lookup, sorting of combining sequences into
  9220. canonical order, etc). This can be added in future releases if there is
  9221. a need (but in many cases, pre- and postpostprocessing might be a
  9222. better option).
  9223. Within these constraints, Kermit converts between the UCS and its other
  9224. character sets. For example, a mixture of Russian and English (and/or
  9225. Dutch, or Latin) text can bet converted between the UCS and ISO
  9226. Latin/Cyrillic or KOI-8. But since Kermit does not presently support
  9227. Arabic character-set conversion, the new availability of UCS conversion
  9228. does not mean that Kermit can convert from Arabic UCS text to some
  9229. other character set, because Kermit does not support any other
  9230. character set that includes Arabic. Ditto for Thai, Armenian, Georgian,
  9231. Tibetan, Chinese, Korean, etc. However, Kermit CAN convert Arabic (or
  9232. any other script) between UCS-2 and UTF-8.
  9233. Considering Cyrillic more carefully, note that the UCS also contains
  9234. numerous Cyrillic characters not found in any of the Cyrillic sets (ISO
  9235. Latin/Cyrillic, KOI8, CP866, etc) that Kermit supports; characters
  9236. needed for Abkhasian, Yakut, Tatar, Bashkir, Altaic, Old Church
  9237. Slavonic, etc; UCS text containing any of these historic or "extended"
  9238. Cyrillic characters can not be converted to any of Kermit's current
  9239. single-byte Cyrillic sets without loss. The situation is similar for
  9240. Greek, Hebrew, etc, and even worse for Japanese since Unicode contains
  9241. thousands of Kanjis that are lacking from the Japanese character sets
  9242. based on JIS X 0208, such as EUC-JP, JIS-7, and Shift-JIS.
  9243. In general, when converting from UCS to a single-byte set, there is
  9244. always the possibility of data loss, just as there is when converting
  9245. from any larger set to a smaller one. For example, if a UCS file
  9246. contains Devanagari characters, these characters will be lost when
  9247. converting to (say) Latin-1, just as Roman vowels with acute accents
  9248. are lost when converting from Latin-1 (an 8-bit set) to German ISO 646
  9249. (a 7-bit set).
  9250. 6.6.5. Kermit's Unicode Features
  9251. C-Kermit can convert between UCS-2 or UTF-8 and any of its other
  9252. character sets, and also between UCS-2 and UTF-8. When converting
  9253. between UCS-2 or UTF-8 and a non-Unicode character set (such as
  9254. Latin-1), the UCS Line Separator (LS, U+2028) and Paragraph Separator
  9255. (PS, U+2029) characters are converted to the appropriate line
  9256. terminator (CR, LF, or CRLF). When converting from a non-Unicode set to
  9257. UCS-2 or UTF-8, however, line terminators are not converted to LS or
  9258. PS. This is in accordance with the recommendations of Unicode Technical
  9259. Report #13.
  9260. When C-Kermit starts, it tests the native byte order of the computer.
  9261. You can see the result in the SHOW FEATURES or SHOW FILE display. It's
  9262. also available in the variable \v(byteorder): 0 means Big Endian, 1
  9263. means Little Endian.
  9264. When UCS-2 is involved in file transfer or translation, the following
  9265. commands tell C-Kermit what to do about byte order:
  9266. SET FILE UCS BYTE-ORDER { BIG-ENDIAN, LITTLE-ENDIAN }
  9267. This is for reading UCS-2 files that don't have a BOM, and also
  9268. for writing UCS-2 files. If this command is not given, the
  9269. machine's native byte order is used when writing UCS-2 files,
  9270. and also when reading UCS-2 files that don't have a BOM.
  9271. SET FILE UCS BOM { ON, OFF }
  9272. This setting is used when creating UCS-2 files. A BOM is added
  9273. at the beginning by default. Use OFF to not add the BOM. This
  9274. command has no affect when writing files.
  9275. COPY /SWAP-BYTES sourcefile destinationfile
  9276. Use this for fixing a UCS-2 file whose bytes are in the wrong
  9277. order.
  9278. Use SHOW FILE to display the FILE UCS settings.
  9279. Please note, again, that C-Kermit's user interface, including its
  9280. script language, is not internationalized in any way. String
  9281. comparisons, case conversion, and so on, work only for US ASCII
  9282. (comparisons for equality work with other sets, but not
  9283. lexically-greater-or-less-than or caseless comparisons; even
  9284. comparisons for equality can fail when composed characters or byte
  9285. order are involved). String functions such as \findex() and
  9286. \fsubstring() that reference byte positions do just that; they won't
  9287. work with UTF-8 text that contains any non-ASCII characters, and they
  9288. will not work with UCS-2 text at all since they use C strings
  9289. internally, which are NUL-terminated. These are just a few examples to
  9290. illustrate that neither Unicode nor any other character-set beyond
  9291. ASCII is supported at the user-interface, command, or scripting level
  9292. in this version of C-Kermit.
  9293. 6.6.5.1. File Transfer
  9294. Kermit supports both UCS-2 and UTF-8 as file and transfer character
  9295. sets in text-mode file transfer.
  9296. To select UCS-2 or UTF-8 as a file character-set, use:
  9297. SET FILE CHARACTER-SET { UCS2, UTF8 }
  9298. If you want to send a UCS-2 text file (or save an incoming file in
  9299. UCS-2 format), tell Kermit to:
  9300. SET FILE CHARACTER-SET UCS2
  9301. and if you want to send a UTF-8 text file (or store an incoming file in
  9302. UTF-8 format), tell Kermit to:
  9303. SET FILE CHARACTER-SET UTF8
  9304. When sending UCS-2 files, Kermit determines the byte order from the
  9305. BOM, if there is one (and if there is a BOM, it is stripped, i.e. not
  9306. sent). If there is no BOM, the byte order is the one specified in the
  9307. most recent SET FILE UCS BYTE-ORDER command, if any, otherwise the
  9308. computer's native byte order is assumed. When storing incoming files as
  9309. UCS-2, the byte order is according SET FILE UCS BYTE-ORDER, if given,
  9310. otherwise the native one; a BOM is written according to SET FILE UCS
  9311. BOM.
  9312. A transfer character-set should be chosen that includes all of the
  9313. characters in the source file. So, for example, if you are sending a
  9314. UCS-2 file containing only German-language text, your transfer
  9315. character-set can be Latin-1, Latin-2, Latin-9, UCS-2, or UTF-8. But if
  9316. you are sending a file that contains a combination of Hebrew and Greek,
  9317. your transfer character-set must be UCS-2 or UTF-8 if you don't want to
  9318. lose one script or the other. Furthermore, the transfer character-set
  9319. must be one that is supported by the receiving Kermit program. Since
  9320. UCS support is new, it is possible that the other Kermit program (if it
  9321. supports character sets at all) does not support it, but does support
  9322. single-byte sets such as Latin-1, Latin/Cyrillic, etc.
  9323. To select UCS-2 or UTF-8 as a transfer character-set, use:
  9324. SET TRANSFER CHARACTER-SET { UCS2, UTF8 }
  9325. It is up to the receiving Kermit program to convert the transfer format
  9326. to its own local format, if necessary. If it does not understand the
  9327. UTF-8 or UCS-2 transfer character-set, and your file can not be
  9328. adequately represented by any single-byte transfer character-set (such
  9329. as Latin-1 or Latin/Cyrillic) then, if UTF-8 format is acceptable on
  9330. the receiving computer, use UTF-8 as the transfer character-set, with
  9331. the receiver told to "set unknown-char keep", or with the sender told
  9332. to "set attribute char off". If you want the file to be stored in UCS-2
  9333. format at the receiver, send it it binary mode if the source file is
  9334. also UCS-2, or else use the TRANSLATE command (next section) to convert
  9335. it to UCS-2 first, then send it in binary mode. You should not use
  9336. UCS-2 as a transfer character-set in text-mode transfers to Kermit
  9337. programs that don't support it, because they are likely to corrupt the
  9338. result the same way FTP would (see the final paragraph of this
  9339. section).
  9340. When UCS-2 is the transfer character set, it always goes into Kermit
  9341. packets in Big Endian format, with no BOM. As always, the transfer
  9342. character-set is announced by the sender to the receiver. The
  9343. announcement for UCS-2 is "I162" (ISO Registration 162 = UCS-2 Level 1)
  9344. and by definition it is Big Endian (the standards say that when UCS-2
  9345. is serialized into bytes, the order must be Big Endian). The
  9346. announcement for UTF-8 is "I190" (UTF-8 Level 1).
  9347. When receiving a file whose transfer character-set is UCS-2 or UTF-8,
  9348. you must choose the appropriate file character set for the result.
  9349. There is no way Kermit can do this for you automatically, since UCS
  9350. data can be in any script at all, or any combination.
  9351. In general, UTF-8 or UCS-2 should be chosen as a transfer character-set
  9352. if the source file is also encoded in some form of UCS and it contains
  9353. more than one script. But there are other situations where where UTF-8
  9354. or UCS-2 offer advantages. For example, suppose the source file is on a
  9355. NeXTstation and the destination file is on VMS. Both the NeXT and the
  9356. DEC Multinational character sets include the French OE digraph, but
  9357. Latin-1 does not. Therefore French words containing this character
  9358. might not arrive intact when Latin-1 is the transfer character-set, but
  9359. will with UTF-8 or UCS-2, since the UCS includes the OE digraph (but so
  9360. does Latin-9).
  9361. UCS-2 should be chosen as a transfer character-set only for Japanese
  9362. text files that contain a large preponderance of Kanji, since in this
  9363. case (and only this case) UCS-2 (two bytes per Kanji) is more efficient
  9364. than UTF-8 (three bytes per Kanji). The same will be true for Chinese
  9365. and Korean when they are supported by Kermit. UCS-2 should never be
  9366. used as a transfer character-set with a transfer partner that does not
  9367. support UCS-2 since this can cause file corruption (see last paragraph
  9368. in this section).
  9369. Note that Kermit's repeat-count compression is 100% ineffective for
  9370. UCS-2, and is also ineffective for multibyte characters in UTF-8 and
  9371. EUC-JP; this is because repeat-compression is a transport-level
  9372. mechanism that operates on a per-byte basis; it has no knowledge of the
  9373. distinction between a byte and a character.
  9374. When C-Kermit starts, it sets up associations ( Section 6.5) for
  9375. incoming files whose transfer character sets are UCS-2 or UTF-8
  9376. appropriately for the platform so that the file character-set for the
  9377. incoming file is UCS-2 in Windows and UTF-8 elsewhere. Otherwise,
  9378. C-Kermit does not make any default associations for UCS-2 or UTF-8, but
  9379. of course you may add or change associations to suit your needs and
  9380. preferences by including the appropriate ASSOCIATE commands in your
  9381. Kermit startup file. For example, if you are a PC user and deal only
  9382. with text written in Greek and English, you can:
  9383. ASSOCIATE TRANSFER-CHARACTER-SET UTF8 CP869
  9384. ASSOCIATE TRANSFER-CHARACTER-SET UCS2 CP869
  9385. ASSOCIATE FILE-CHARACTER-SET CP869 UTF8
  9386. Note that when file transfer involves conversion between a single-byte
  9387. character set and UCS-2 or UTF-8, the file-transfer thermometer and
  9388. estimated time left might be inaccurate, since they are based on the
  9389. source file size, not the transfer encoding. This is purely a cosmetic
  9390. issue and does not effect the final result. (And is not, strictly
  9391. speaking, a bug; Kermit protocol presently includes no method for the
  9392. sender to furnish an "estimated transfer size" to the receiver, and in
  9393. any case any such guess could be as far off as the file size, given the
  9394. many other factors that come into play, such as compression and
  9395. prefixing).
  9396. A caution about FTP and UCS-2. As noted previously, if you transfer a
  9397. UCS-2 file with FTP in binary mode between two computers with opposite
  9398. Endianness, the result will have its bytes in the wrong order. However,
  9399. if you use FTP to transfer a UCS-2 file in "ascii" (text) mode to ANY
  9400. computer, even if it is identical to yours, the result will be
  9401. corrupted because FTP's line-terminator conversions do not account for
  9402. UCS-2. The same holds when sending from a UCS-aware Kermit program to
  9403. an older Kermit program in text mode with a transfer character-set of
  9404. UCS-2. So use UCS-2 as a transfer character-set ONLY with a UCS-2-aware
  9405. Kermit partner.
  9406. 6.6.5.2. The TRANSLATE Command
  9407. In Kermit versions that have Unicode support included, TRANSLATE now
  9408. always goes through Unicode; that is, the source set is converted to
  9409. UCS-2 and thence to the target set. This is a major improvement, since
  9410. in prior releases, C-Kermit had to pick the "most appropriate" transfer
  9411. character-set as the intermediate set, and this would result in the
  9412. loss of any characters that the source and target sets had in common
  9413. but were lacking from the intermediate set (for example the OE digraph
  9414. when translating from NeXT to DEC MCS through Latin-1). This never
  9415. happens when Unicode is the intermediate set because Unicode is a
  9416. superset of all other character sets supported by Kermit. A more
  9417. dramatic example would be translation between Cyrillic PC code page 866
  9418. and KOI8-R ( Section 6.4); formerly all the line- and box-drawing
  9419. characters would be lost (since ISO 8859-5 does not have any); now the
  9420. ones that these two sets have in common are preserved.
  9421. UCS-2 and UTF-8 are now both supported as source-file and
  9422. destination-file character sets by C-Kermit's TRANSLATE command, for
  9423. example:
  9424. translate oofa.txt ucs2 latin1 oofa-l1.txt
  9425. translates oofa.txt from UCS-2 to Latin-1, storing the result as
  9426. oofa-l1.txt. Similarly:
  9427. translate oofa.txt utf8 latin1 oofa-l1.txt
  9428. translate oofa.txt latin1 ucs2 oofa-ucs2.txt
  9429. translate oofa.txt latin1 utf8 oofa-utf8.txt
  9430. translate oofa.txt ucs2 utf8 oofa-utf8.txt
  9431. translate oofa.txt utf8 ucs2 oofa-ucs2.txt
  9432. Treatment of the UCS-2 BOM is exactly the same as for file transfer.
  9433. Note that if a UCS-2 source file is in the "wrong" byte order and lacks
  9434. a BOM, and you don't tell Kermit about it with SET FILE UCS BYTE-ORDER,
  9435. the result of the translation is total gibberish. Recall that you can
  9436. use COPY /SWAP-BYTES to switch the byte order of an errant UCS-2 file
  9437. (or any other file for that matter, if you can think of a reason to).
  9438. Also note that:
  9439. translate oofa.txt ucs2 ucs2 new.txt
  9440. Produces a result in the native (or SET FILE UCS) byte-order as long as
  9441. oofa.txt has a BOM.
  9442. As a side benefit of the Unicode work, the TRANSLATE command now works
  9443. for the first time also for all Japanese character sets that Kermit
  9444. supports. In other words, if you have a Japanese text file in any of
  9445. the following encodings:
  9446. EUC-JP
  9447. Shift-JIS
  9448. JIS-7
  9449. UCS-2
  9450. UTF-8
  9451. You can use the TRANSLATE command to convert to any other encoding from
  9452. the same list.
  9453. 6.6.5.3. Terminal Connection
  9454. The CONNECT command now allows UTF-8 as a local or remote terminal
  9455. character-set:
  9456. SET TERMINAL CHARACTER-SET { ..., UTF8 } { ..., UTF8 }
  9457. SET TERMINAL REMOTE-CHARACTER-SET { ..., UTF8 }
  9458. SET TERMINAL LOCAL-CHARACTER-SET { ..., UTF8 }
  9459. (Recall that Kermit's terminal character-set has two "ends" -- the set
  9460. used on the host to which Kermit is connected, and the set used on the
  9461. local keyboard and screen.)
  9462. UCS-2 is not supported as a terminal character-set (either end) since
  9463. (a) it is not used that way anywhere to our knowledge, and (b) the
  9464. problems of Endianness and the high likelihood of loss of
  9465. synchronization make it impractical. (Telecommunications is
  9466. byte-oriented; if one byte, or any odd number of bytes, is lost because
  9467. of buffer overruns, circuit resets, etc (or likewise if a burst of
  9468. noise appears that takes the guise of an odd number of bytes), the byte
  9469. order of the subsequent data stream will be backwards; unlike UTF-8 and
  9470. traditional byte-based character sets, UCS-2 is not "self
  9471. synchronizing".)
  9472. UTF-8 does not have byte-order or synchronization problems and is
  9473. growing in popularity as a terminal character set as well as in other
  9474. application areas. It allows a single terminal session to use multiple
  9475. scripts (Roman, Cyrillic, Greek, etc) without ISO 2022 character-set
  9476. switching (which terminal emulators like Kermit 95 can handle but few
  9477. host applications understand or use), and meshes nicely with the
  9478. Unicode screen fonts that are beginning to appear.
  9479. UTF-8 was first used in Plan 9 and soon will be available in Linux. It
  9480. will probably spread from there (Unicode in some form is, of course,
  9481. also used in Windows NT, but only internally -- not for access from
  9482. outside).
  9483. To use UTF-8 or any other character set that uses 8-bit bytes in your
  9484. terminal session, be sure to tell C-Kermit to:
  9485. SET TERMINAL BYTESIZE 8
  9486. SET COMMAND BYTESIZE 8
  9487. SET PARITY NONE
  9488. (or use the shortcut command, EIGHTBIT, which does all three at once).
  9489. In a setup where your local Kermit program uses a single-byte character
  9490. set such as PC Code Page 850 and the remote host uses UTF-8:
  9491. SET TERM CHAR UTF8 CP850
  9492. or:
  9493. SET TERM REMOTE CHAR UTF8
  9494. SET TERM LOCAL CHAR CP850
  9495. all works as expected. UTF-8 text on the remote displays correctly on
  9496. your screen, and when you type CP850 characters, they are translated to
  9497. UTF-8 sequences for transmission, and the echo from the host is
  9498. translated from UTF-8 back to CP850. Telnet negotiations and
  9499. autodownload take place before any character-set translation and work
  9500. as before. The session log (if text mode was selected for it) contains
  9501. only the local terminal character-set. And so on.
  9502. Kermit merely supplies translations from UTF-8 to your local terminal
  9503. character-set (this includes treating UTF-8 Line Separator and
  9504. Paragraph separator as CRLF). However, Kermit does does not, at
  9505. present, perform "canonicalization" of composed sequences, nor does it
  9506. automatically execute bidirectionality algorithms for display of
  9507. mixed-direction text (e.g. Hebrew and English). Such presentation
  9508. issues, like all others in the terminal-host regime, are left to the
  9509. host.
  9510. By the way, C-Kermit also allows UTF-8 to be the local end of the
  9511. terminal character-set, but so far this code is not tested, since we
  9512. don't have a UTF-8 console or terminal to work with. However, it can be
  9513. stated without doubt that C-Kermit's key mapping will not work for
  9514. UTF-8 values, since (a) the key map is indexed by 8-bit byte values and
  9515. (b) C-Kermit reads keystrokes a byte at a time (these comments do not
  9516. apply to K95, which has direct access to the keyboard and can read
  9517. "wide" keycodes and uses them to index a "wide" keymap).
  9518. Restrictions: As noted, the CONNECT command does not support UCS-2 as a
  9519. REMOTE TERMINAL character-set. Neither does it support the Japanese
  9520. sets EUC-JP, JIS-7, and Shift-JIS. Support for the Japanese sets (and
  9521. possibly Chinese and Korean too) might be added in a future release.
  9522. Since the TRANSMIT command (next section) uses the same REMOTE TERMINAL
  9523. character-sets as the CONNECT command, it has the same restrictions.
  9524. 6.6.5.4. The TRANSMIT Command
  9525. As described in Chapter 15 ofUsing C-Kermit and Section 4.21
  9526. of this document, the TRANSMIT command can be used to upload a file
  9527. without protocol, more or less as if you were typing it on your
  9528. keyboard while connected to the host. When TRANSMITting in text mode,
  9529. the file's character set is converted to the host's unless you have SET
  9530. TERMINAL CHARACTER-SET TRANSPARENT, or you include the new TRANSMIT
  9531. switch, /TRANSPARENT.
  9532. Before C-Kermit 7.0, the file character-set was assumed to be the same
  9533. as the local end of the terminal character-set, and the TRANSMIT
  9534. command used the same translations as the CONNECT command, ignoring the
  9535. file character-set.
  9536. In C-Kermit 7.0, that assumption (a poor one to begin with) can no
  9537. longer be made, since UCS-2 can be a file character-set but not a
  9538. terminal character-set. So now the file's character-set is given by
  9539. your most recent SET FILE CHARACTER-SET command. The host's character
  9540. set is the remote end of your most recent SET TERMINAL CHARACTER-SET
  9541. command:
  9542. SET TERMINAL CHARACTER-SET remote-set [ local-set ]
  9543. or:
  9544. SET TERMINAL REMOTE-CHARACTER-SET remote-set
  9545. The TRANSMIT command converts each source-file character from the FILE
  9546. character-set to the REMOTE TERMINAL character-set, and then transmits
  9547. the translated characters according to your SET TRANSMIT preferences
  9548. (Chapter 15).
  9549. If you have SET TRANSMIT ECHO ON, and the host is echoing the
  9550. transmitted characters, the echos are converted from the remote
  9551. terminal character-set to the local terminal character-set.
  9552. [ A picture would help... ]
  9553. Confused? Let's work through an example. Suppose your local computer is
  9554. a NeXTstation, on which text files are encoded in the NeXT character
  9555. set, and that the remote computer is a Data General AViiON, which uses
  9556. the Data General International character set. Further suppose that you
  9557. are logged in to the NeXT from a VT220 terminal which uses the DEC
  9558. Multinational character set.
  9559. You need to convert the file from NeXT encoding to DG encoding and
  9560. convert the echoes from DG encoding to DEC encoding. So on the NeXT,
  9561. tell C-Kermit to:
  9562. eightbit
  9563. set file character-set next
  9564. set term character-set dg-international dec-mcs
  9565. transmit /text nextdata.txt
  9566. (This assumes you have some sort of collection process already set up
  9567. on the Data General, such as a text editor or the venerable "cat >
  9568. foo". The EIGHTBIT command is equivalent to SET TERMINAL BYTESIZE 8,
  9569. SET COMMAND BYTESIZE 8, SET PARITY NONE.)
  9570. To further complicate matters, suppose your local terminal character
  9571. set is the same as the remote one, so you don't need terminal
  9572. character-set translation, but you need to TRANSMIT a file that is in a
  9573. different character set and you want it translated to the host set. In
  9574. this case, use SET TERM CHARACTER-SET to actually specify the character
  9575. set used on each end, rather than specifying TRANSPARENT:
  9576. eightbit
  9577. set file character-set ucs2
  9578. set term character-set latin1 latin1
  9579. transmit /text ucs2data.txt
  9580. The distinction between:
  9581. SET TERMINAL CHARACTER-SET xxx yyy
  9582. (where xxx and yyy are the same set) and:
  9583. SET TERMINAL CHARACTER-SET TRANSPARENT
  9584. is new to C-Kermit 7.0, but affects only the TRANSMIT command.
  9585. The TRANSMIT command currently does nothing special with UCS-2/UTF-8
  9586. Line and Paragraph Separator characters; more experience is required to
  9587. find out how these behave in a genuine Unicode terminal-host setting.
  9588. Restrictions: As noted, the TRANSMIT command translates from the FILE
  9589. character-set to the REMOTE TERMINAL character-set. This rules out
  9590. translations to any character set that is not supported as a REMOTE
  9591. TERMINAL character-set, such as UCS-2, EUC-JP, JIS-7, and Shift-JIS.
  9592. 6.6.5.5. Summary of Kermit Unicode Commands
  9593. Specifying file character-set and byte order:
  9594. SET FILE CHARACTER-SET { ..., UCS2, UTF8 }
  9595. REMOTE SET FILE CHARACTER-SET { ..., UCS2, UTF8 } (See next
  9596. section)
  9597. SET FILE UCS BOM { ON, OFF }
  9598. SET FILE UCS BYTE-ORDER { BIG-ENDIAN, LITTLE-ENDIAN }
  9599. Specifying the transfer character-set:
  9600. SET TRANSFER CHARACTER-SET { ..., UCS-2, UTF-8 }
  9601. REMOTE SET TRANSFER CHARACTER-SET { ..., UCS-2, UTF-8 }
  9602. Specifying the terminal character-set:
  9603. SET TERMINAL CHARACTER-SET { ..., UTF8 } { ..., UTF8 }
  9604. SET TERMINAL REMOTE-CHARACTER-SET { ..., UTF8 }
  9605. SET TERMINAL LOCAL-CHARACTER-SET { ..., UTF8 }
  9606. Displaying settings:
  9607. SHOW FILE
  9608. SHOW TRANSFER
  9609. SHOW TERMINAL
  9610. SHOW CHARACTER-SETS
  9611. Commands that use these settings include:
  9612. SEND, RECEIVE, GET, etc.
  9613. CONNECT
  9614. TRANSMIT
  9615. LOG SESSION
  9616. Converting files:
  9617. TRANSLATE infile { ..., UCS-2, UTF-8 } { ..., UCS-2, UTF-8 }
  9618. outfile
  9619. COPY /SWAP-BYTES infile outfile
  9620. 6.7. Client/Server Character-Set Switching
  9621. A simple mechanism has been added to allow the client to change the
  9622. server's FILE CHARACTER-SET:
  9623. REMOTE SET FILE CHARACTER-SET name
  9624. The client asks the server to change its file character-set to
  9625. the one given. The name must match one of the server's file
  9626. character-set names. For convenience, C-Kermit uses its own file
  9627. character-set keyword list for parsing this command so you can
  9628. use ? for help and Tab or Esc for completion. However, since the
  9629. server might have a different repertoire (or even use different
  9630. names for the same sets), C-Kermit accepts any string you supply
  9631. and sends it to the server. The server, if it supports this
  9632. command (C-Kermit 7.0 and K95 1.1.19 do), sets its file
  9633. character-set as requested, and also disables automatic
  9634. character-set switching ( Section 6.5). If the server does
  9635. not support this command or if it does not support the given
  9636. character set, the REMOTE SET FILE CHARACTER-SET command fails.
  9637. Here's an example that sends a Japanese text file encoded in Shift-JIS
  9638. to a server using every combination of Kermit's Japanese-capable file
  9639. and transfer character sets:
  9640. dcl \&x[] = euc ucs2 utf8 ; transfer character-sets
  9641. dcl \&y[] = eu uc ut ; 2-letter abbreviations for them
  9642. dcl \&f[] = shift euc jis7 ucs2 utf8 ; file character-sets
  9643. dcl \&g[] = sj eu j7 uc ut ; 2-letter abbreviations
  9644. set file char shift-jis ; local file character-set is Shift-JIS
  9645. for \%i 1 \fdim(&x) 1 { ; for each transfer character-set...
  9646. set xfer char \&x[\%i] ; set it
  9647. for \%j 1 \fdim(&f) 1 { ; for each remote file character-set...
  9648. remote set file char \&f[\%j] ; set it
  9649. if fail exit 1 SERVER REJECTED CHARSET
  9650. send /text meibo-sj.html meibo-sj-\&y[\%i]-\&g[\%j].txt ; send the fil
  9651. e
  9652. if fail exit 1 TRANSFER FAILED
  9653. }
  9654. }
  9655. The Kermit-370 server does not support REMOTE SET FILE CHARACTER-SET,
  9656. but since it supports REMOTE KERMIT commands, you can get the same
  9657. effect with REMOTE KERMIT SET FILE CHARACTER-SET name.
  9658. 7. SCRIPT PROGRAMMING
  9659. (Also see Section 2.8, Scripting Local Programs.)
  9660. 7.0. Bug Fixes
  9661. The following script programming bugs were fixed in C-Kermit 7.0:
  9662. * IF EXIST and IF DIRECTORY were fixed to properly strip braces from
  9663. around their arguments, so "if directory {C:\Program Files}", etc,
  9664. would work as expected. However, this means that if the file or
  9665. directory name is actually enclosed in braces, the braces must be
  9666. doubled.
  9667. * The READ command did not fail if the READ file wasn't open; now it
  9668. does.
  9669. * The READ command refused to read the last or only line of a file if
  9670. it did not end with a proper line terminator; now it does.
  9671. * The END command, when given from within a SWITCH statement, did not
  9672. exit from the current macro or command file; instead it just
  9673. terminated the SWITCH.
  9674. 7.1. The INPUT Command
  9675. 7.1.1. INPUT Timeouts
  9676. The description of the INPUT command on page 422 fails to mention the
  9677. following two points about the timeout (which apply to C-Kermit 6.0 and
  9678. later):
  9679. 1. "INPUT -1 text" (or "INPUT \%x text", where \%x is any variable
  9680. whose value is -1 or less) means "wait forever". This form of the
  9681. INPUT command fails only if it is interrupted, since it will never
  9682. time out.
  9683. 2. INPUT 0 performs a nonblocking read of material that has already
  9684. arrived but has not yet been read, and succeeds immediately if the
  9685. target string is found, or fails immediately if it is not found.
  9686. The same points apply to MINPUT. REINPUT ignores its timeout parameter.
  9687. 7.1.2. New INPUT Controls
  9688. The following new INPUT controls were added in version 7.0:
  9689. SET INPUT AUTODOWNLOAD { ON, OFF }
  9690. Explained in Section 7.7.
  9691. SET INPUT CANCELLATION { ON, OFF }
  9692. This governs whether an INPUT command can be canceled by
  9693. "pressing any key" on the keyboard. Normally it can be, in which
  9694. case the INPUT command fails immediately and \v(instatus) is set
  9695. to 2, indicating interruption. SET INPUT CANCELLATION OFF
  9696. disables keyboard cancellations; thus if the search text is not
  9697. encountered, the INPUT command will run for its entire timeout
  9698. interval. SET INPUT CANCELLATION OFF does not disable
  9699. interruption by Ctrl-C, however; every command needs an
  9700. emergency exit. (If you really want to disable interruption by
  9701. Ctrl-C, use SET COMMAND INTERRUPTION OFF.)
  9702. Also see Section 7.2 for any new variables related to INPUT.
  9703. 7.1.3. INPUT with Pattern Matching
  9704. C-Kermit 7.0 allows INPUT, MINPUT, and REINPUT targets to be a pattern
  9705. (explained inSections 1.19 and4.9). This solves a
  9706. long-standing problem illustrated by the following scenario: a certain
  9707. company has a bank of TCP/IP modem servers, with hostnames server1,
  9708. server2, server3, and so on. Each server's prompt is its name, followed
  9709. by a colon (:), for example "Server72:". Without INPUT patterns, it
  9710. would be rather difficult to wait for the prompt. The brute force
  9711. approach:
  9712. minput 20 Server1: Server2: Server3: ... (enumerating each one)
  9713. is subject to failure whenever a new server is added. A more subtle
  9714. approach:
  9715. input 20 Server
  9716. if fail ...
  9717. input 2 :
  9718. is liable to false positives, e.g. "Welcome to the XYZ Corp Modem
  9719. Server. Please read the following message:"...
  9720. With patterns, you can match the prompt with "Server*:" (which doesn't
  9721. solve the "false positives" problem, but certainly is more compact than
  9722. the brute force method), or with more specific patterns such as
  9723. "Server[1-9]:" and "Server[1-9][0-9]:", or equivalently:
  9724. Server{[1-9],[1-9][0-9]}:
  9725. meaning the word "Server" followed by a single digit (1-9) or by two
  9726. digits representing a number from 1 to 99, followed by a colon.
  9727. INPUT pattern matching has been added in a way that does not interfere
  9728. with existing scripts. No new commands or switches are used. The simple
  9729. rule is: if an INPUT search target is the argument of the (new)
  9730. \fpattern() function, it is a pattern. Otherwise it is taken literally,
  9731. as before. For example:
  9732. input 5 a*b
  9733. searches for an 'a' followed by an asterisk ('*'), followed by a 'b'.
  9734. But:
  9735. input 5 \fpattern(a*b)
  9736. searches for an 'a' followed by anything at all up to and including the
  9737. first 'b'. This means that any search target to INPUT, MINPUT, or
  9738. REINPUT can be a pattern or a literal string, and in particular that
  9739. MINPUT can accommodate any mixture of patterns and literal strings.
  9740. In selecting patterns, note that:
  9741. * A leading '*' is always implied so there is no need to include one.
  9742. * A trailing '*' is meaningless and ignored.
  9743. * A '*' by itself matches the first character that arrives.
  9744. A syntax note: If your pattern is a selection list, meaning a list of
  9745. alternatives separated by commas and enclosed in braces, then the outer
  9746. braces will be stripped by various levels of parsers, so you must
  9747. include three of each:
  9748. input 10 \fpattern({{{abc,mno,xyz}}})
  9749. Note that this is equivalent to:
  9750. minput 10 abc mno xyz
  9751. except for the setting of the \v(minput) variable.
  9752. And a caution: INPUT pattern matching has a limitation that you
  9753. probably never noticed with literal-string matching, namely that there
  9754. is a limit on the size of the match. For example, if the pattern is
  9755. "a*b", the match will succeed if the 'a' and 'b' are not separated by
  9756. more than (say) 8K bytes, but will fail if they are farther apart than
  9757. that. In such cases, it better to use two INPUTs (e.g. "input 10 a" and
  9758. then "input 100 b").
  9759. 7.1.4. The INPUT Match Result
  9760. The result of any INPUT, MINPUT, or REINPUT command, no matter whether
  9761. the search targets are patterns or literal strings, is available in the
  9762. new \v(inmatch) variable. For example:
  9763. minput 10 cat \fpattern([dh]og)
  9764. if success echo MINPUT matched "\v(inmatch)"
  9765. This is especially useful when a pattern was matched, since it makes
  9766. the string that matched the pattern available to Kermit; there would be
  9767. no way to get it otherwise.
  9768. After an INPUT command, you can view all the INPUT-related variables by
  9769. typing "show variables in" (abbreviate as "sho var in"), which shows
  9770. the values of all built-in variables whose names start with "in".
  9771. 7.2. New or Improved Built-In Variables
  9772. \v(blockcheck)
  9773. Current BLOCK-CHECK setting, 1, 2, 3, or 4. 4 is the code for
  9774. BLANK-FREE-2.
  9775. \v(byteorder)
  9776. The machine's byte order: 0 = Big Endian, 1 = Little Endian.
  9777. \v(cmdbufsize)
  9778. The length of the command buffer, which is the maximum size for
  9779. a macro, a command, a variable, or anything else in C-Kermit's
  9780. script language.
  9781. \v(ctty)
  9782. The device name of C-Kermit's controlling (login) terminal.
  9783. \v(filename)
  9784. Described inSections 4.1 and4.2.
  9785. \v(filenumber)
  9786. Described inSections 4.1 and4.2.
  9787. \v(filespec)
  9788. As of C-Kermit 7.0, contains fully qualified filenames rather
  9789. than (usually) relative ones.
  9790. \v(return)
  9791. Now holds the END n value of the macro that most recently
  9792. returned, in case END was used rather than RETURN.
  9793. \v(editor)
  9794. Pathname of preferred text editor
  9795. \v(editopts)
  9796. Command-line options for editor
  9797. \v(editfile)
  9798. File most recently edited
  9799. \v(browser)
  9800. Pathname of preferred Web browser
  9801. \v(browsopts)
  9802. Command-line options for Web browser
  9803. \v(browsurl)
  9804. URL most recently given to Web browser
  9805. \v(dialtype)
  9806. Type of call most recently placed (see Section 2.1.11).
  9807. \v(kbchar)
  9808. The character, if any, that was typed at the keyboard to to
  9809. interrupt the most recent PAUSE, SLEEP, WAIT, MSLEEP, or INPUT
  9810. command; empty if the most recent such command was not
  9811. interrupted from the keyboard.
  9812. \v(lockdir)
  9813. UNIX only - The name of the UUCP lockfile directory, if known,
  9814. otherwise "(unknown)".
  9815. \v(lockpid)
  9816. UNIX only - PID of process that owns the communication port that
  9817. you tried to open with a SET LINE command that failed because
  9818. the port was in use, otherwise empty. This variable is set with
  9819. every SET LINE command.
  9820. \v(cx_time)
  9821. If no connection (SET HOST, SET LINE, DIAL, TELNET, etc) is
  9822. active, this is 0. If a connection is active, this is the number
  9823. of seconds since the connection was made.
  9824. \v(hwparity)
  9825. If hardware parity is in effect, this variable gives its value,
  9826. such as "even" or "odd" (in which case, the \v(parity) variable
  9827. will be "none"). Otherwise this variable is empty.
  9828. \v(serial)
  9829. Current serial port settings in 8N1 format ( Section 2.10).
  9830. \v(errno)
  9831. In UNIX, the current value of the C runtime errno variable,
  9832. which is quite volatile (meaning that often an "interesting"
  9833. error code can be overwritten by some other library call or
  9834. system service that sets errno before you have a chance to look
  9835. at it). In VMS, the error code returned by the system or library
  9836. call that most recently failed (success codes are not saved).
  9837. Not available in other operating systems.
  9838. \v(errstring)
  9839. The UNIX or VMS system error message that corresponds to
  9840. \v(errno). Not available in all OS's. Also see
  9841. \ferrstring().
  9842. \v(setlinemsg)
  9843. The error message, if any, from the most recent SET LINE, SET
  9844. PORT, SET HOST, TELNET, or other connection-making command. This
  9845. is not necessarily the same as \v(errstring) since these
  9846. commands might fail without generating a system error code, for
  9847. example (in UNIX) because a lockfile existed indicating the
  9848. device was assigned by another user.
  9849. \v(exitstatus)
  9850. The exit status C-Kermit would return if it exited now.
  9851. \v(pexitstat)
  9852. The exit status of the inferior process most recently invoked by
  9853. C-Kermit (by RUN, !, REDIRECT, SEND /COMMAND, etc). In VMS, this
  9854. code can be given to \ferrstring() to get the corresponding
  9855. error message (in UNIX, program/command return codes are not the
  9856. same as system error codes). Not available in operating systems
  9857. other than UNIX and VMS. See Section 4.2.5 for details.
  9858. \v(inmatch)
  9859. The incoming string of characters, if any, that matched the most
  9860. recent INPUT, REINPUT, or MINPUT command.
  9861. \v(intime)
  9862. The number of milliseconds (thousandths of seconds) it took for
  9863. the most recent INPUT command to find its match, or -1 if no
  9864. INPUT command has been given yet. If the INPUT command timed
  9865. out, the value is approximately equal to 1000 times the INPUT
  9866. timeout. If INPUT failed for some other reason, the value is
  9867. undefined (\v(instatus) gives INPUT completion status). If your
  9868. version of C-Kermit is built without high-precision
  9869. floating-point timers, this number will always be a multiple of
  9870. 1000.
  9871. \v(inwait)
  9872. The number of seconds specified as the timeout in the most
  9873. recent INPUT command.
  9874. \v(dialsuffix)
  9875. Dialing suffix for use during PDIAL sequence; seeSection
  9876. 2.1.10.
  9877. \v(pid)
  9878. UNIX, VMS, and K95 only. C-Kermit's primary process ID, numeric,
  9879. decimal. If you want to show it in hex, use \fn2hex(\v(pid)) If
  9880. you want to show it in octal, use \fn2octal(\v(pid)).
  9881. \v(printer)
  9882. Current printer name or SET PRINTER value.
  9883. \v(p_ctl)
  9884. Control prefix char \v(p_8bit) 8-bit prefix char (if parity not
  9885. none)
  9886. \v(p_rpt)
  9887. Repeat prefix char (if repeat compression enabled)
  9888. \v(herald)
  9889. Kermit's version herald
  9890. \v(test)
  9891. Kermit's test version, if any, or 0 if this is not a test
  9892. version. Typical values for test versions are "Alpha.03" or
  9893. "Beta.14".
  9894. \v(sendlist)
  9895. The number of entries in the SEND-LIST, 0 if none. Note: entries
  9896. do not necessarily correspond to files, since an entry might
  9897. contain wildcards. Also note that the value does not go back to
  9898. 0 after the files in the list are sent. To reset this variable,
  9899. use CLEAR SEND-LIST. The purpose of this variable is to
  9900. determine if a SEND command, when given without any filenames,
  9901. will be legal. Example:
  9902. xif \v(sendlist) { send } else { send oofa.txt }
  9903. \v(trigger)
  9904. If the most recent CONNECT session was terminated automatically
  9905. by a trigger, this variable contains the trigger value.
  9906. \v(ty_ln)
  9907. TYPE line number (during TYPE)
  9908. \v(ty_lc)
  9909. TYPE line count (after TYPE)
  9910. \v(ty_mc)
  9911. TYPE match count (after TYPE)
  9912. \v(xferstat)
  9913. Status of most recent file transfer:
  9914. -1: No transfer yet
  9915. 0: Succeeded
  9916. 1: Failed
  9917. \v(xfermsg)
  9918. If the most recent file transfer failed, this is the reason. If
  9919. it succeeded, \v(xfermsg) is an empty string.
  9920. \v(tftime)
  9921. Total elapsed time of most recent file transfer operation, in
  9922. seconds.
  9923. \v(textdir)
  9924. Directory that holds (or is supposed to hold) Kermit text files
  9925. such as installation instructions, release notes, update notes,
  9926. read-me files, "beware" files, etc.
  9927. \v(name)
  9928. The name with which the Kermit program was invoked, e.g.
  9929. "kermit", "wermit", "k95", "k2", etc (see Section 9.1).
  9930. \v(osname)
  9931. Name of operating system on computer where C-Kermit is running,
  9932. obtained at runtime (from uname or equivalent).
  9933. \v(osversion)
  9934. Version of operating system on computer where C-Kermit is
  9935. running, obtained at runtime (from uname or equivalent).
  9936. \v(osrelease)
  9937. Release of operating system on computer where C-Kermit is
  9938. running, obtained at runtime (from uname or equivalent).
  9939. \v(model)
  9940. The specific hardware model of the computer where C-Kermit is
  9941. running, if known.
  9942. \v(math_pi)
  9943. The value of Pi (see Section 7.23)
  9944. \v(math_e)
  9945. The value of e (see Section 7.23)
  9946. \v(math_precision)
  9947. How many significant digits in a floating-point number.
  9948. \v(f_count)
  9949. Result of the most recent FILE COUNT (FCOUNT) command.
  9950. \v(f_error)
  9951. Numeric error code of most recent FILE command.
  9952. \v(f_max)
  9953. Maximum number of files open simultaneously.
  9954. The math constants are given in the precision of underlying computer's
  9955. floating-point arithmetic.
  9956. Note the distinction between \v(osname), \v(osversion), and
  9957. \v(platform); the latter refers to the platform for which and/or upon
  9958. which C-Kermit was built, as opposed to the one on which it is actually
  9959. running. Also note that each operating system can, and probably will,
  9960. interpret and fill in the os* variables differently, or not at all.
  9961. The SHOW VARIABLES command now accepts a variable name, prefix, or
  9962. pattern:
  9963. show variables Shows all variables.
  9964. show variables t Shows all variables that start with "t".
  9965. show variables *ver* Shows all variables whose names contain "ver".
  9966. show variables *ver Ditto (an implied "*" is appended).
  9967. 7.3. New or Improved Built-In Functions
  9968. The following new file-i/o functions are explained inSection
  9969. 1.22.
  9970. \f_status(channel) Status of file open on channel
  9971. \f_pos(channel) Read/write (byte) pointer of given file
  9972. \f_line(channel) Current line of file
  9973. \f_handle(channel) Handle of file
  9974. \f_eof(channel) Whether given file is at EOF
  9975. \f_getchar(channel) Read a char from given file
  9976. \f_getline(channel) Read a line from given file
  9977. \f_getblock(channel,n) Read a block from given file
  9978. \f_putchar(channel,c) Write a char to given file
  9979. \f_putline(channel,string) Write a line to given file
  9980. \f_putblock(channel,string) Write a block to given file
  9981. The following new date-time-related functions are explained in
  9982. Section 1.6:
  9983. \fday() Returns day of week of given date
  9984. \fnday() Returns numeric day of week of given date
  9985. \ftime() Returns time portion of given date-time
  9986. \fntime() Converts time to seconds since midnight
  9987. \fn2time() Converts seconds since midnight to hh:mm:ss
  9988. \fcvtdate(date-time) Converts free-format date to yyyymmdd hh:mm:ss
  9989. \fdayofyear(date-time) Converts date to yyyyddd (day-of-year) format
  9990. \fdoy(date-time) Synonym for \fdayofyear()
  9991. \fdoy2date(dayofyear) Converts yyyyddd to yyyymmdd
  9992. \fmjd(date-time) Converts free-format date to Modified Julian Date
  9993. \fmjd2date(mjd) Converts modified Julian date to yyyymmdd
  9994. The new floating-point arithmetic functions are explained in
  9995. Section 7.23. f1 and f2 are floating-point (real) numbers; d is
  9996. the number of decimal places to show:
  9997. \ffpabsolute(f1,d) Absolute value of f1
  9998. \ffpadd(f1,f2,d) f1 + f1
  9999. \ffpcosine(f1,d) Cosine of f1
  10000. \ffpdivide(f1,f2,d) f1 divided by f2
  10001. \ffpexp(f1,d) e to the f1 power
  10002. \ffpint(f1) Integer part of f1
  10003. \ffplog10(f1,d) Log base 10 of f1
  10004. \ffplogn(f1,d) Natural log of f1
  10005. \ffpmaximum(f1,f2,d) Maximum of f1 and f2
  10006. \ffpminimum(f1,f2,d) Minimum of f1 and f2
  10007. \ffpmodulus(f1,f2,d) Modulus of f1 and f2
  10008. \ffpmultiply(f1,f2,d) Product of f1 and f2
  10009. \ffpraise(f1,f2,d) Raise f1 to power f2
  10010. \ffpround(f1,d) Round f1 to d places
  10011. \ffpsine(f1,d) Sine of f1
  10012. \ffpsqrt(f1,d) Square root of f1
  10013. \ffpsubtract(f1,f2,d) f2 - f1
  10014. \ffptangent(f1,d) Tangent of f1
  10015. Integer number functions:
  10016. \fabsolute(n)
  10017. Absolute value of integer n.
  10018. \frandom(n)
  10019. Returns a random integer between 0 and n-1.
  10020. \fradix(s,n1,n2)
  10021. If the string s is an integer in radix n1, the result is the
  10022. same number expressed in radix n2, where n1 and n2 may be any
  10023. number from 2 through 36, expressed as decimal numbers, or
  10024. variables (etc) that evaluate to decimal numbers. For the source
  10025. and result, the digits of any radix, r, are the first r
  10026. characters in the sequence 0-9,a-z (case doesn't matter for the
  10027. letters). The string s may have a sign, + or -; if it starts
  10028. with a minus (-) sign, the result also has a minus sign.
  10029. The \fradix() function does not work with floating-point numbers. It
  10030. does not reveal the internal storage format of a number; for example,
  10031. \fradix(-1,10,16) is -1, not something like FFFFFFFFFF. If all three
  10032. arguments are not given, or if n1 or n2 are not numbers between 2 and
  10033. 36 inclusive, or s is not a number in radix n1, an error occurs and the
  10034. empty string is returned. \fradix() also does not offer
  10035. extended-precision arithmetic; number values are limited to those
  10036. expressed as a long integer in the architecture of the underlying
  10037. computer, usually 32 or 64 bits. If you give it an argument whose
  10038. absolute value is larger than can be held in an unsigned long, the
  10039. result is -1.
  10040. The next four are shorthand functions for decimal/hexadecimal and
  10041. decimal/octal number conversion:
  10042. \fn2hex(n)
  10043. Returns the hexadecimal (base 16) representation of the integer
  10044. n. This is different from \fhexify(s), which treats its argument
  10045. as a string rather than a number. The result is always
  10046. left-padded with 0's to make its length even. Examples:
  10047. \n2hex(0) = "00" \fhexify(0) = "30"
  10048. \n2hex(255) = "ff" \fhexify(255) = "323535"
  10049. \n2hex(256) = "0100" \fhexify(256) = "323536"
  10050. \fhex2n(x)
  10051. Converts hexadecimal number x to decimal equivalent decimal
  10052. number. This is the inverse of \fn2hex(). Equivalent to
  10053. \fradix(s,16,10).
  10054. \fn2octal(n)
  10055. Returns the octal (base 8) representation of the number n.
  10056. Examples:
  10057. \n2octal(0) = "0"
  10058. \n2oct(255) = "377"
  10059. \n2oct(256) = "400"
  10060. Equivalent to \fradix(n,10,8).
  10061. \foct2n(n)
  10062. Returns the decimal representation of the given octal number, n.
  10063. The inverse of \fn2octal(). Equivalent to \fradix(n,8,10).
  10064. String functions:
  10065. \s(name[n:m])
  10066. Equivalent to \fsubstring(\m(name),n,m) ( Section 7.24).
  10067. \:(name[n:m])
  10068. Equivalent to \fsubstring(name,n,m) (where "name" is any
  10069. \-quantity) ( Section 7.24).
  10070. \fleft(s,n)
  10071. The leftmost ncharacters of string s; equivalent to
  10072. \fsubstring(s,1,n).
  10073. \fstripx(string,char)
  10074. Returns the part of the string up to the rightmost occurrence,
  10075. if any, of the given character. The default character is period
  10076. (.) Examples:
  10077. \fstripx(foo/bar,/) = "foo"
  10078. \fstripx(foo/bar/baz,/) = "foo/bar"
  10079. \fstripx(autoexec.bat,.) = "autoexec"
  10080. \fstripx(autoexec.bat) = "autoexec"
  10081. \fstripx(fstripx(foo/bar/baz,/),/) = "foo"
  10082. \flop(string,character)
  10083. Returns the portion of the string starting after the first
  10084. occurrence of the given character. The default character is
  10085. period (.) Examples:
  10086. \flop(autoexec.bat) = "bat"
  10087. \flop(baz.foo/bar) = "foo/bar"
  10088. \flop(baz.foo/bar,/) = "bar
  10089. \fstripn(string,n)
  10090. Returns the string with ncharacters removed from the end.
  10091. Example:
  10092. \fstripn(12345678,3) = "12345"
  10093. (For more discussion of \fstripx(), \fstripn(), and \flop() see
  10094. Section 4.2.3).
  10095. \fb64encode(s)
  10096. Returns the Base-64 encoding of the string s.
  10097. \fb64decode(s)
  10098. Returns the decoding of the Base-64 string s. Fails if s is not
  10099. a Base-64 string, or if its length is not a multiple of 4. Note
  10100. that if any of the result bytes are null (0), the result string
  10101. stops there. There is no way to represent strings that contain
  10102. null bytes in C-Kermit (the same is true for \funhexify()).
  10103. \fword(s1,n,s2,s3)
  10104. Extracts word number nfrom string s1. By default, a "word" is
  10105. any sequence of ASCII letters or digits; nis 1-based. If n is
  10106. omitted, "1" is used. Examples:
  10107. \fword(one two three) = "one"
  10108. \fword(one two three,1) = "one"
  10109. \fword(one two three,2) = "two"
  10110. \fword(one two three,3) = "three"
  10111. and:
  10112. \fword(\v(dialresult),2) = "31200"
  10113. is "31200" if \v(dialresult) is (e.g.) "CONNECT
  10114. 31200/ARQ/V32/LAPM/V42BIS".
  10115. If you include s2, this replaces the default break set. For
  10116. example, suppose you have a string \%a whose value is:
  10117. $150.00 $300.00 $39.95
  10118. and you want each dollar amount to be a word; use:
  10119. \fword(\%a,\%n,{ })
  10120. This returns dollar amount number \%n, e.g. "$300.00" for \%n =
  10121. 2. "{ }" denotes a space (you must enclose it in braces,
  10122. otherwise it is squeezed out). Note that ASCII control
  10123. characters are always included in the break set; you don't have
  10124. to specify them (and you can't not specify them).
  10125. The optional s3 argument lists characters (even control
  10126. characters) that normally would be considered separators that
  10127. you want included in words. So the dollars-and-cents example
  10128. could also be handled this way:
  10129. \fword(\%a,\%n,,$.)
  10130. in other words, use the default separator list, but remove "$"
  10131. and "." from it so they will be considered part of a word.
  10132. Note that since 8-bit characters are not ASCII, they act as
  10133. break characters unless you put them in the include list.
  10134. Suppose, for example, you have a file in which each line is a
  10135. Tab-separated list of words, numbers, or phrases that might
  10136. contain punctuation, special characters like $ and @, 8-bit bit
  10137. characters, etc (like something that might have been exported
  10138. from a spreadsheet or database), and you want to split only on
  10139. Tab; here is a way (\m(line) is a line read from the file):
  10140. undef keep
  10141. for \%i 1 255 1 {
  10142. if == \%i 9 continue
  10143. .keep := \m(keep)\fchar(\%i)
  10144. }
  10145. while true {
  10146. fread /line \%c line
  10147. if fail break
  10148. .\%n := \fsplit(\m(line),&a,\9,\m(keep))
  10149. ...
  10150. }
  10151. This problem is addressed inC-Kermit 9.0.
  10152. \fsplit(s1,&a,s2,s3)
  10153. This is like \fword(), except instead of extracting and
  10154. returning a particular word from string s1, it counts the words
  10155. and optionally assigns them to the array whose identifying
  10156. letter, a-z, is given after the "&" in the second argument, with
  10157. the first word going into element 1, the second into element 2,
  10158. and so on. The rules regarding break and include lists (s2 and
  10159. s3) are exactly the same as for \fword(). \fsplit() returns the
  10160. number of words that were assigned, which is either the number
  10161. of words in the string, or the dimension of the array, whichever
  10162. is less. If the array is not declared, \fsplit() creates it and
  10163. returns a number which is both the number of words in s1 and the
  10164. dimension of the new array. Examples:
  10165. declare \&w[20] ; (Optional.)
  10166. ...
  10167. read \%s ; \%s is "This is a sentence with seven words."
  10168. ...
  10169. echo "\fsplit(\%s)" ; This would print "7".
  10170. echo "\fsplit(\%s,&w)" ; Ditto, and also assigns them to array \&w[].
  10171. echo "\&w[7]" ; This would print "words".
  10172. If the line contained fields that were delimited by colon (:),
  10173. you would use \fsplit(\%s,&w,:). If the fields were delimited by
  10174. comma, then you would use \fsplit(\%s,&w,{,}); in this case the
  10175. literal comma must be enclosed in braces to distinguish it from
  10176. the comma that separates function arguments. To get a word count
  10177. without loading an array, but still specify break and/or include
  10178. lists, leave the array argument empty:
  10179. echo "\fsplit(\%s,,:)" ; Use colon as the separator.
  10180. WARNINGS:
  10181. 1. If you use the same array repeatedly, \fsplit() leaves any
  10182. trailing members undisturbed. For example:
  10183. dcl \&w[10]
  10184. \fsplit(1 2 3 4 5,&w) ; Sets \&w[1] thru \&w[5].
  10185. \fsplit(a b c,&w) ; Sets \&w[1]-[3] leaving [4]-[5] as they were.
  10186. 2. If you allow \fsplit to create the array (by not declaring it
  10187. first), it is dimensioned to the number of elements it was
  10188. created with:
  10189. \fsplit(1 2 3,&x) ; Creates an array \&x[] with 3 elements.
  10190. \fsplit(a b c d e,&x) ; This overflows the array.
  10191. Thus if you want to use \fsplit() repeatedly on the same array,
  10192. either dimension it in advance to the maximum expected size (and
  10193. then some -- more efficient), or else destroy it after each use
  10194. (to allow for unexpectedly large arguments). Example using a
  10195. dynamic array:
  10196. fopen /read \%c some-file
  10197. if fail ...
  10198. set function error on ; See Section 7.12
  10199. while true {
  10200. dcl \&w[] ; Destroy \&[w] each time thru the loop
  10201. fread /line \%c \%a
  10202. if fail break
  10203. asg \%x \fsplit(\%a,&w)
  10204. if fail ...
  10205. ; (do what you want with \&w[] here...)
  10206. }
  10207. fclose \%c
  10208. \frindex(s1,s2,n)
  10209. The "n" argument to \frindex() now works consistently (in mirror
  10210. image) with the corresponding \findex() argument. In each case,
  10211. the (n-1)-most characters of s2 are ignored in the search; for
  10212. findex, this means the starting position of the search is n (the
  10213. default n is 1, and 0 is treated like 1). For \frindex() it
  10214. means the default starting point is:
  10215. length(s2) - length(s1) - n (with the same defaults for n).
  10216. \fsearch(pattern,string[,position])
  10217. Exactly like \findex(), except with a pattern (seeSection
  10218. 7.9) rather than a literal string.
  10219. \frsearch(pattern,string[,position])
  10220. Exactly like \frindex(), except with a pattern rather than a
  10221. literal string.
  10222. File Functions:
  10223. \ffiles(), \fnextfile()
  10224. It is no longer necessary to copy the file list to an array
  10225. before use, as shown on p.398 ofUsing C-Kermit 2nd
  10226. Edition. \ffiles() and friends now make their own safe copies of
  10227. the file list. Thus constructions like the following are now
  10228. possible:
  10229. for \%i 1 \ffiles(*.txt) 1 { send \fnextfile() }
  10230. The same is true for the new function \frfiles(),
  10231. \fdirectories(), and \frdirectories(), described inSection
  10232. 4.11.3.
  10233. But note that each reference to \fnextfile() still gets you the
  10234. next file. So "if newer \fnextfile() foo.txt send \fnextfile()"
  10235. compares one file's age with that of foo.txt, and then sends an
  10236. entirely different file. If you're going to refer to the same
  10237. file more than once, assign it to a variable:
  10238. asg \%f \fnextfile()
  10239. if newer \%f foo.txt send \%f
  10240. (note: assign, not define).
  10241. Also note that \ffiles(), \frfiles(), \fdirectories(), and
  10242. \frdirectories() all now accept on optional 2nd argument: the
  10243. name of an array to load with the resulting file or directory
  10244. list, explained in Section 4.11.3. So you can also load an
  10245. array with the filelist when you need to refer to the same file
  10246. more than once:
  10247. for \%i 1 \ffiles(*,&a) 1 { if newer \&a[\%i] foo.txt send \&a[\%i] }
  10248. \fpermissions(file)
  10249. Returns the platform-specific permissions string for the file,
  10250. such as "-rw-rw-r--" in UNIX or "(RWE,RWE,RE,E)" in VMS.
  10251. \fdirname(f)
  10252. Given a file specification f, this function returns the complete
  10253. pathname of directory the file is in.
  10254. Array Functions:
  10255. \fdimension(&a)
  10256. Returns the dimension declared for the array whose identifying
  10257. letter, a-z, or special character "_" or "@", is given after the
  10258. "&" in the argument. If the array is not declared, 0 is
  10259. returned. Note that when used with the macro argument vector
  10260. array, \&_[] (see Section 7.5), the value of this function
  10261. is one less than \v(argc), and when used with the C-Kermit
  10262. command-line argument vector array, \&@[], it is equal to the
  10263. \v(args) variable. Examples:
  10264. echo \fdimension(&a) ; Not declared.
  10265. 0
  10266. declare \&a[12] ; Now it's declared.
  10267. echo \fdim(&a)
  10268. 12
  10269. \farraylook(pattern,arrayname)
  10270. Looks in the given array for the pattern and returns the index
  10271. of the first element that matches, if any, or -1 if none match.
  10272. The arrayname can include a range specifier to restrict to
  10273. search to a segment of the array, e.g.
  10274. \farraylook(*xyz*,&a[32:63]). For greater detail see
  10275. Section 7.10.7.
  10276. \ftablelook(keyword,arrayname[,delimiter])
  10277. Looks in the given "table", which must be sorted, for the given
  10278. keyword. Returns the index of the table element that uniquely
  10279. matches the given keyword, or -1 if none match, or -2 if more
  10280. than 1 match. For greater detail see Section 7.10.7.
  10281. Other new functions:
  10282. \fip2hex(s)
  10283. Converts a dotted decimal IP address to an 8-digit hexadecimal
  10284. number. \fip2hex(128.59.39.2) = 803b2702.
  10285. \fhex2ip(x)
  10286. Converts an 8-digit hexadecimal IP address to dotted decimal
  10287. form, e.g. \fhex2ip(803b2702) = 128.59.39.2. The inverse of
  10288. \fip2hex().
  10289. \fcommand()
  10290. \frawcommand()
  10291. These run an external command and return its output; see
  10292. Section 4.2.8.4.
  10293. \fdialconvert(s)
  10294. s is a phone number in either literal or portable format (not a
  10295. dialing directory entry name). The function returns the dial
  10296. string that would actually be used when dialing from the current
  10297. location (after processing country code, area code, and other
  10298. SET DIAL values).
  10299. \ferrstring(n)
  10300. Returns the system error message associated with the (numeric)
  10301. error code n. UNIX and VMS only. Use in conjunction with
  10302. \v(errno) or \v(pexitstat). See Section 4.2.5 for a usage
  10303. example. Note: This function doesn't work in Windows because
  10304. there is not a consistent error-code-to-message mapping; error
  10305. code "x" means something completely different depending on
  10306. whether it comes from the C runtime library, Winsock, a
  10307. Windows-32 API, TAPI, etc,
  10308. \fpattern(s)
  10309. Used in INPUT, REINPUT, and MINPUT commands to denote search
  10310. strings that are to be treated as patterns rather than
  10311. literally.
  10312. Also see Section 7.8 on built-in help for functions.
  10313. 7.4. New IF Conditions
  10314. IF AVAILABLE feature command
  10315. Executes the command if the given feature is available.
  10316. Presently used only to determine if specific authentication and
  10317. encryption options are available. Type "if available ?" to see
  10318. which features may be tested.
  10319. IF FLOAT f1 command
  10320. Executes command if f1 is a legal floating point number (which
  10321. includes integers). Use this to preverify arguments for the
  10322. \ffp...() floating-point arithmetic functions, e.g. "if float
  10323. \%1 echo \ffpint(\%1)".
  10324. IF == n1 n2 command
  10325. Synonym for "if =" (numeric equality). Note that as of C-Kermit
  10326. 7.0, this and all other numeric comparison operators also work
  10327. for floating-point numbers.
  10328. IF != n1 n2 command
  10329. Executes the command if n1 and n2 are both numbers or variables
  10330. containing numbers and the value of n1 is not equal to the value
  10331. of n2. This is equivalent to "if not = n1 n2".
  10332. IF <= n1 n2 command
  10333. Executes the command if n1 and n2 are both numbers or variables
  10334. containing numbers and the value of n1 is less than or equal to
  10335. the value of n2. This is equivalent to "if not > n1 n2".
  10336. IF >= n1 n2 command
  10337. Executes the command if n1 and n2 are both numbers or variables
  10338. containing numbers and the value of n1 is greater than or equal
  10339. to the value of n2. Equivalent to "if not < n1 n2".
  10340. IF COMMAND word command
  10341. Executes the command if word is a built-in C-Kermit command.
  10342. Example:
  10343. if not command copy define { copy run copy \%1 \%2 }".
  10344. This defines a COPY macro that runs an external COPY command if
  10345. COPY is not already a built-in command.
  10346. IF LOCAL command
  10347. Executes the command if Kermit is in local mode, i.e. if it has
  10348. a SET LINE, SET PORT, or SET HOST (TELNET, RLOGIN, etc) device
  10349. or connection open. Does not execute the command if in remote
  10350. mode.
  10351. IF MATCH string pattern command
  10352. Executes the command if the string matches the pattern. For a
  10353. description of the syntax for the pattern, seeSection
  10354. 4.9.1. If you want to test if the string contains pattern, use
  10355. IF \fsearch(pattern,string).
  10356. IF OPEN { DEBUG-LOG, SESSION-LOG, TRANSACTION-LOG, ... } command
  10357. Executes the command if the given file is open, fails if it is
  10358. not open. Type IF OPEN ? for a complete list of files that can
  10359. be checked (all the files that can be opened with the OPEN or
  10360. LOG commands).
  10361. IF QUIET command
  10362. Executes the command if SET QUIET is ON, and does not execute it
  10363. if SET QUIET is OFF. Example: IF NOT QUIET ECHO { This is a
  10364. message.}.
  10365. IF READABLE name
  10366. Succeeds if name is the name of an existing file or directory
  10367. that is readable.
  10368. IF WRITEABLE name
  10369. Succeeds if name is the name of an existing file or directory
  10370. that is writable, e.g.:
  10371. if not writeable \v(lockdir) echo Please read installation instructions!
  10372. IF FLAG command
  10373. This tests a user-settable condition, which can mean anything
  10374. you like. SET FLAG ON causes subsequent IF FLAG commands to
  10375. succeed; SET FLAG OFF causes them to fail. One way to use it
  10376. would be for debugging your scripts; precede any debugging
  10377. statements with IF FLAG. Then SET FLAG on to debug your script,
  10378. SET FLAG OFF to run it without debugging. Another common use is
  10379. for causing an inner loop to cause an outer loop to exit.
  10380. IF C-KERMIT command
  10381. C-Kermit, but not Kermit 95 or MS-DOS Kermit, executes the
  10382. command.
  10383. IF K-95 command
  10384. Kermit 95, but not C-Kermit or MS-DOS Kermit, executes the
  10385. command.
  10386. IF MS-KERMIT command
  10387. MS-DOS Kermit, but not C-Kermit or Kermit 95, executes the
  10388. command.
  10389. 7.5. Using More than Ten Macro Arguments
  10390. The \v(argc) variable now gives the actual number of arguments, even if
  10391. the number is greater than 9:
  10392. C-Kermit> define xx echo \v(argc)
  10393. C-Kermit> xx a b c d e f g h i j k l m n o p q r s t u v w x y z
  10394. 27
  10395. Remember that \v(argc) includes the name of the macro itself, so it is
  10396. always at least 1, and is always 1 greater than the actual number of
  10397. arguments. As in versions 6.0 and earlier, if more than 9 arguments are
  10398. given, only the first nine are assigned to the variables \%1..\%9.
  10399. The \&_[] array, discussed on page 353 ofUsing C-Kermit, 2nd ed,
  10400. now holds all the arguments, up to some implementation-dependent limit
  10401. (64 or greater), rather than only the first 9. To illustrate: the
  10402. following macro tells the number of arguments it was called with and
  10403. then prints them:
  10404. define show_all_args {
  10405. local \%i
  10406. echo \&_[0] - Number of arguments: \feval(\v(argc)-1)
  10407. for \%i 1 \v(argc)-1 1 { echo \flpad(\%i,3). "\&_[\%i]" }
  10408. }
  10409. Within a macro \&_[0], like \%0, contains the name of the macro.
  10410. At top level, the \&_[] array is filled as follows:
  10411. * If the first argument on the C-Kermit command line was a filename,
  10412. or C-Kermit was invoked from a "Kerbang" script (Section
  10413. 7.19), element 0 contains the filename, and elements 1 through
  10414. \v(argc)-1 hold the remaining command-line arguments.
  10415. * Otherwise the program name goes in element 0, and elements 1
  10416. through \v(argc)-1 hold any arguments that were included after "--"
  10417. or "="
  10418. The new \%* variable, when used within a macro, is replaced by the text
  10419. that followed the macro name in the macro invocation. If no arguments
  10420. were given, \%* is replaced by the empty string. Examples:
  10421. C-Kermit> define xx echo [\%*]
  10422. C-Kermit> define \%a oofa
  10423. C-Kermit> xx
  10424. []
  10425. C-Kermit> xx \%a
  10426. [oofa]
  10427. C-Kermit> xx a
  10428. [a]
  10429. C-Kermit> xx a b
  10430. [a b]
  10431. C-Kermit> xx a b c
  10432. [a b c]
  10433. C-Kermit> xx a b c d e f g h i j k l m n o p q r s t u v w x y z
  10434. [a b c d e f g h i j k l m n o p q r s t u v w x y z]
  10435. Note that \%* can not be used at top level, since Kermit does not have
  10436. access to the raw command line (only to its elements separately, after
  10437. they have been processed by the shell and the C library).
  10438. C-Kermit 7.0 also adds a SHIFT command:
  10439. SHIFT [ number ]
  10440. Shifts the macro arguments (except argument 0) the given number
  10441. of places to the left and adjusts \v(argc) accordingly. The
  10442. default number is 1.
  10443. To illustrate, suppose macro XXX is invoked as follows:
  10444. xxx arg1 arg2 arg3
  10445. Then inside XXX, \%1 is "arg1", \%2 is "arg2", and \%3 is "arg3". After
  10446. a SHIFT command is given inside XXX, then \%1 is "arg2", \%2 is "arg3",
  10447. and \%3 is empty. \%0 (the name of the macro) remains unchanged.
  10448. If more than 9 arguments were given, then arguments are shifted into
  10449. the \%1..9 variables from the argument vector array.
  10450. At top level, the SHIFT command operates on the \&_[] array and \%1..9
  10451. variables; the \&@[] array is not affected. See Section 7.16 for
  10452. details.
  10453. The \%* variable is not affected by the SHIFT command.
  10454. 7.6. Clarification of Function Call Syntax
  10455. Spaces are normally stripped from the front and back of each function
  10456. argument; to prevent this enclose the argument in braces:
  10457. \fsplit(\%a,&a,{ })
  10458. However, function calls that contain spaces can make trouble when the
  10459. function is to be used in a "word" field, since space separates words.
  10460. For example:
  10461. for \%i 1 \fsplit(\%a,&a,{ }) 1 {
  10462. echo \%i. "\&a[\%i]"
  10463. }
  10464. In most cases, the trouble can be averted by enclosing the function
  10465. reference in braces:
  10466. for \%i 1 {\fsplit(\%a,&a,{ })} 1 {
  10467. echo \%i. "\&a[\%i]"
  10468. }
  10469. or by replacing spaces with \32 (the ASCII code for space):
  10470. for \%i 1 \fsplit(\%a,&a,\32) 1 {
  10471. echo \%i. "\&a[\%i]"
  10472. }
  10473. Braces are also used in function calls to indicate grouping. For
  10474. example:
  10475. \fsubstring(abcd,2,2) = "bc"
  10476. But suppose "abcd" needed to contain a comma:
  10477. \fsubstring(ab,cd,2,2)
  10478. This would cause an error, since "cd" appears to be the second
  10479. argument, when really you want the first "2" to be the second argument.
  10480. Braces to the rescue:
  10481. \fsubstring({ab,cd},2,2) = "b,"
  10482. Similarly, leading and trailing spaces are stripped from each argument,
  10483. so:
  10484. \fsubstring( abcd ,2,2) = "bc"
  10485. but braces preserve them:
  10486. \fsubstring({ abcd },2,2) = "ab"
  10487. Given these special uses for braces, there is no way to pass literal
  10488. braces to the function itself. For example:
  10489. \fsubstring(ab{cd,2,2)
  10490. causes an error.
  10491. So if you need a function to include braces, define a variable
  10492. containing the string that has braces. Example:
  10493. define \%a ab{cd
  10494. \fsubstring(\%a,2,2) = "b{"
  10495. If the string is to start with a leading brace and end with a closing
  10496. brace, then double braces must appear around the string (which itself
  10497. is enclosed in braces):
  10498. define \%a {{{foo}}}
  10499. \fsubstring(\%a) = "{foo}"
  10500. This also works for any other kind of string:
  10501. define \%a {{ab{cd}}
  10502. echo \fsubstring(\%a) = "ab{cd"
  10503. 7.7. Autodownload during INPUT Command Execution
  10504. As of 6.1 / 1.1.12, C-Kermit can be told to look for incoming Kermit
  10505. (or Zmodem) packets during execution of an INPUT command. By default
  10506. (for consistency with earlier releases), this is not done. You can
  10507. enable this feature with:
  10508. SET INPUT AUTODOWNLOAD ON
  10509. (and disable it again with OFF.)
  10510. One possible use for this feature is as a server mode with a time
  10511. limit:
  10512. INPUT 3600 secret-string-to-end-the-INPUT-command
  10513. In this example, any GET, SEND, or REMOTE commands received within one
  10514. hour (3600 seconds) of when the INPUT command was issued will be
  10515. executed. Here's another example, in which we want to stay open until
  10516. 11:30pm, or until interrupted by seven consecutive Ctrl-C (\3)
  10517. characters:
  10518. INPUT 23:30:00 \3\3\3\3\3\3\3
  10519. The INPUT AUTODOWNLOAD setting is displayed by SHOW SCRIPTS or SHOW
  10520. INPUT.
  10521. 7.8. Built-in Help for Functions.
  10522. Beginning in C-Kermit 7.0, you may obtain a description of the calling
  10523. conventions and return values of any built-in function, such as
  10524. \fsubstring(), with the new HELP FUNCTION command; give the function's
  10525. name without the leading "\f", e.g. "help func substring". You can use
  10526. ?, completion, and abbreviation in the normal manner.
  10527. 7.9. Variable Assignments
  10528. 7.9.1. Assignment Operators
  10529. Programmers accustomed to languages such as C or Fortran might find
  10530. Kermit's method of assigning values to variables unnatural or awkward.
  10531. Beginning in C-Kermit 7.0, you can use the following alternative
  10532. notation:
  10533. .name = value is equivalent to DEFINE name value
  10534. .name := value is equivalent to ASSIGN name value
  10535. .name ::= value is equivalent to ASSIGN name \feval(value)
  10536. When the command begins with a period (.), this indicates an
  10537. assignment. The name can be a macro name, a \%{digit,letter} variable,
  10538. or an array element. There can be space(s) between "." and the name.
  10539. Examples:
  10540. .\%a = This is a string ; Same as "define \%a This is a string"
  10541. echo \%a
  10542. This is a string
  10543. .xxx = \%a ; Same as "define xxx \%a"
  10544. echo \m(xxx)
  10545. \%a
  10546. .xxx := \%a ; Same as "assign xxx \%a"
  10547. echo \m(xxx)
  10548. This is a string
  10549. declare \&a[2] ; Use with arrays...
  10550. define \%i 2
  10551. .\&a[1] = first
  10552. .\&a[\%i] = second
  10553. The following sequence illustrates the differences among three levels
  10554. of evaluation:
  10555. .\%x = 2 ; Define a variable to have a numeric value
  10556. .\%y = (3 + \%x) ; Define another variable as an arithmetic expression
  10557. .xxx = 4 * \%y ; "=" simply copies the right-hand side.
  10558. echo \m(xxx)
  10559. 4 * \%y
  10560. .xxx := 4 * \%y ; ":=" evaluates the variables first, then copies.
  10561. echo \m(xxx)
  10562. 4 * (3 + 2)
  10563. .xxx ::= 4 * \%y ; "::=" evaluates the expression, then copies.
  10564. echo \m(xxx)
  10565. 20
  10566. You can also use this syntax to clear (undefine) a variable:
  10567. .\%a = oofa ; Define the variable
  10568. echo "\%a"
  10569. "oofa"
  10570. .\%a ; Clear the variable
  10571. echo "\%a"
  10572. ""
  10573. Extra credit: Can you guess what happens below when the file "abc" does
  10574. not exist?
  10575. fopen /read \%c abc
  10576. if fail ...
  10577. 7.9.2. New Assignment Commands
  10578. Recall the DEFINE and ASSIGN commands, and their hidden counterparts,
  10579. _DEFINE and _ASSIGN. The former take the variable name literally, the
  10580. latter evaluate the variable-name field to form the variable name
  10581. dynamically. Examples:
  10582. DEFINE \%x foo ; Sets the value of the variable \%x to "foo".
  10583. DEFINE \%a \%x ; Sets the value of the variable \%a to "\%x".
  10584. _DEFINE x_\%a \%x ; Sets the value of the variable x_foo to "\%x".
  10585. ASSIGN \%a \%x ; Sets the value of the variable \%a to the "foo".
  10586. _ASSIGN x_\%a \%x ; Sets the value of the variable x_foo to "foo".
  10587. This concept has been carried over to the remaining variable-assignment
  10588. commands: EVALUATE, INCREMENT, and DECREMENT:
  10589. EVALUATE variablename expression
  10590. Evaluates the arithmetic expression and assigns its value to the
  10591. variable whose name is given. Example: "eval \%a 1+1" assigns
  10592. "2" to \%a.
  10593. _EVALUATE metaname expression
  10594. Evaluates the arithmetic expression and assigns its value to the
  10595. variable whose name is computed from the given metaname.
  10596. Example: "eval foo<\%a>::\%1 \%2 * (\%3 + \%4)" assigns the
  10597. value of "\%2 * (\%3 + \%4)" to the variable whose name is
  10598. computed from "foo<\%a>::\%1".
  10599. INCREMENT variablename [ expression ]
  10600. Evaluates the arithmetic expression and adds its value to the
  10601. value of the variable whose name is given. Example: "increment
  10602. \%a".
  10603. _INCREMENT metaname [ expression ]
  10604. Evaluates the arithmetic expression and adds its value to the
  10605. value of the variable whose name is computed from the given
  10606. metaname. Example: "_increment Words::\%1.count[\%2]".
  10607. DECREMENT variablename [ expression ]
  10608. Evaluates the arithmetic expression and subtracts its value from
  10609. the value of the variable whose name is given.
  10610. _DECREMENT metaname [ expression ]
  10611. Evaluates the arithmetic expression and subtracts its value from
  10612. the value of the variable whose name is computed from the given
  10613. metaname.
  10614. WARNING: The syntax of the EVALUATE command has changed since C-Kermit
  10615. 6.0 and K95 1.1.17. Previously, it did not include a variable name,
  10616. only an expression. To restore the old behavior, use SET EVALUATE OLD.
  10617. To return to the new behavior after restoring the old behavior, use SET
  10618. EVALUATE NEW.
  10619. NOTE: There are no analogs to the "_" commands for the operators
  10620. described in Section 7.9.1; those operators can not be used to
  10621. assign values to variables whose names must be computed.
  10622. 7.10. Arrays
  10623. C-Kermit 7.0 adds lots of new array-related features, and groups them
  10624. together under the NEW ARRAY command:
  10625. ARRAY { CLEAR, COPY, DECLARE, DESTROY, RESIZE, SHOW, SORT }
  10626. In each of the ARRAY commands, wherever an array name is expected,
  10627. "short forms" may be used. For example, all of the following are
  10628. acceptable:
  10629. array show \&a[] (or SHOW ARRAY...)
  10630. array show &a[]
  10631. array show a[]
  10632. array show &a
  10633. array show a
  10634. In addition, ranges are accepted in the ARRAY COPY, ARRAY CLEAR, ARRAY
  10635. SET, ARRAY SHOW, and ARRAY SORT commands:
  10636. array clear \&a[16] ; Clears 16 thru end
  10637. array clear &a[16] ; Ditto
  10638. array clear a[16] ; Ditto
  10639. array clear \&a[16:32] ; Clears 16 thru 32
  10640. array clear &a[16:32] ; Ditto
  10641. array clear a[16:32] ; Ditto
  10642. When using array names as function arguments, you must omit the "\" and
  10643. you must include the "&". You may optionally include empty brackets.
  10644. Examples:
  10645. \fsplit(\%a,a) ; Bad
  10646. \fsplit(\%a,\&a) ; Bad
  10647. \fsplit(\%a,&a[3]) ; Bad
  10648. \fsplit(\%a,&a) ; Good
  10649. \fsplit(\%a,&a[]) ; Good
  10650. 7.10.1. Array Initializers
  10651. Beginning in C-Kermit 7.0, you may initialize an array -- in whole or
  10652. in part -- in its declaration:
  10653. [ ARRAY ] DECLARE array-name[size] [ = ] [ value1 [ value2 [...] ] ]
  10654. For compatibility with versions 5A and 6.0, the ARRAY keyword is
  10655. optional. DECLARE can also be spelled DCL.
  10656. Initializers are (a) optional, (b) start with element 1, (c) must be
  10657. enclosed in braces if they contain spaces, and (d) are evaluated
  10658. according to normal rules by the DECLARE command prior to assignment.
  10659. Thus the assignments made here are the same as those made by the ASSIGN
  10660. command. This allows you to initialize array elements from the values
  10661. of other variables. If you actually want to initialize an array element
  10662. to variable's name, as opposed to its value, use double backslashes (as
  10663. in "\\&a", "\\v(time)", etc).
  10664. The size (dimension) of the array is optional. If the size is omitted,
  10665. as in "\&a[]", then the array sizes itself to the number of
  10666. initializers; if there are no initializers the array is not declared
  10667. or, if it was declared previously, it is destroyed. If a size is given,
  10668. any extra elements in the initialization list are discarded and
  10669. ignored.
  10670. NOTE: Unlike in C, the list of initializers is NOT enclosed in braces.
  10671. Instead, braces are used to group multiple words together. So:
  10672. ARRAY DECLARE \&a[] = { one two three }
  10673. would create an array with two elements (0 and 1), with element 1
  10674. having the value " one two three ".
  10675. Examples:
  10676. ARRAY DECLARE \&a[16]
  10677. Declares the array \&a with 17 elements (0 through 16), in which
  10678. all elements are initially empty. If the array \&a[] existed
  10679. before, the earlier copy is destroyed.
  10680. ARRAY DECLARE &a[16]
  10681. ARRAY DECLARE a[16]
  10682. ARRAY DCL \&a[16]
  10683. ARRAY DCL &a[16]
  10684. ARRAY DCL a[16]
  10685. DECLARE \&a[16]
  10686. DECLARE &a[16]
  10687. DECLARE a[16]
  10688. DCL \&a[16]
  10689. DCL &a[16]
  10690. DCL a[16]
  10691. All of the above are the same as the first example.
  10692. ARRAY DECLARE \&a[16] = alpha beta {gamma delta}
  10693. Declares the array \&a with 17 elements (0 through 16),
  10694. initializing \&a[1] to "alpha", \&a[2] to "beta", and \&a[3] to
  10695. "gamma delta". The remaining elements are empty.
  10696. ARRAY DECLARE \&a[] = alpha beta {gamma delta}
  10697. Same as the previous example, but the array is automatically
  10698. dimensioned to 3.
  10699. ARRAY DECLARE \&a[3] = alpha beta {gamma delta} epsilon zeta
  10700. Too many initializers; only the first three are kept.
  10701. ARRAY DECLARE \&a[0]
  10702. ARRAY DECLARE \&a[]
  10703. ARRAY DECLARE &a[]
  10704. ARRAY DECLARE &a
  10705. ARRAY DECLARE a
  10706. DECLARE \&[0]
  10707. DECLARE a
  10708. DCL a
  10709. All of these are equivalent. Each destroys \&a[] if it exists.
  10710. Declaring an array with a dimension of 0 is the same as ARRAY
  10711. DESTROY arrayname.
  10712. ARRAY DECLARE \&a[] = \%1 \%2 \%3
  10713. Declares the array \&a with 3 elements (0 through 3),
  10714. initializing \&a[1] to the value of \%1, \&a[2] to the value of
  10715. \%2, and \&a[3] to the value of \%3. In this case, any reference
  10716. to one of these array elements is replaced by the value of the
  10717. corresponding \%n variable at the time the declaration was
  10718. executed (immediate evaluation; the array element's value does
  10719. not change if the initializer variable's value changes).
  10720. ARRAY DECLARE \&a[] = \\%1 \\%2 \\%3
  10721. Declares the array \&a with 3 elements (0 through 3),
  10722. initializing \&a[1] to the string "\%1", \&a[2] to "\%2", and
  10723. \&a[3] to "\%3". In this case any reference to one of these
  10724. array elements is replaced by the CURRENT value of the
  10725. corresponding \%n variable (deferred evaluation -- the array
  10726. element's value follows the value of the initializer variable).
  10727. The equal sign (=) preceding the initializer list is optional, but is
  10728. recommended for clarity. If you need to initialize element 1 to a
  10729. literal equal sign, use two of them, separated by a space, as in this
  10730. example:
  10731. ARRAY DECLARE \&a[] = = + - * /
  10732. Remember, element 0 is not initialized by the DECLARE command. To
  10733. initialize element 0, use a regular DEFINE or ASSIGN command:
  10734. ARRAY DECLARE \&a[] one two three four five six seven eight nine
  10735. DEFINE \&a[0] zero
  10736. Finally, remember that every command level has its own local array,
  10737. \&_[], containing all the macro arguments (\%0, \%1, ...) for that
  10738. level. See Section 7.5 for details.
  10739. 7.10.2. Turning a String into an Array of Words
  10740. The \fsplit(s1,&a,s2,s3) function assigns the words of string s1 to
  10741. successive elements of the array (beginning with element 1) whose
  10742. identifying letter, a-z, is given after the "&" in the second argument,
  10743. using break and include characters given in s2 and s3. SeeSection
  10744. 7.3 for details.
  10745. 7.10.3. Arrays of Filenames
  10746. See Section 4.11.3 for news about how \ffiles() and related
  10747. functions can assign a list of filenames to an array. To recapitulate
  10748. briefly here:
  10749. \ffiles(*,&a)
  10750. assigns all files that match the first argument to the array denoted by
  10751. the second argument. If the array has not been declared, it is declared
  10752. automatically, with exactly the number of elements needed to hold the
  10753. file list; if it was previously declared, it is destroyed and reused.
  10754. The filenames are assigned starting at array element 1. Element 0 holds
  10755. the number of files in the list.
  10756. The DIRECTORY command ( Section 4.5.1) can also create filename
  10757. arrays if you give it the /ARRAY: switch; this allows selection
  10758. criteria beyond whether the filename matches the given pattern.
  10759. All functions and commands that create filename arrays store the number
  10760. of filenames, n, as element 0 of the array, and the filenames as
  10761. elements 1 through n.
  10762. 7.10.4. Automatic Arrays
  10763. In a command file or macro, you can now have local (automatic) arrays.
  10764. Just give the name followed by empty subscript brackets (no spaces
  10765. inside the brackets please) in a LOCAL command, and then declare the
  10766. array:
  10767. LOCAL \%a \&a[] oofa
  10768. ARRAY DECLARE \&a[32] = value1 value2 value3 ...
  10769. This declares the scalar variable \%a, the array \&a[], and the macro
  10770. name "oofa" to be local, and then declares the new local copy of \&a[]
  10771. with 32 elements, perhaps assigning some initial values. When C-Kermit
  10772. exits from the command file or macro containing these command, the
  10773. previous \&a[] array is restored (and if there was no \&a[] at any
  10774. higher level, this will still be true). The process can be repeated to
  10775. any level. Thus it is now safe to write scripts or macros containing
  10776. arrays without danger of interfering with global arrays of the same
  10777. name.
  10778. Just as scalars are inherited by lower command levels, so are arrays.
  10779. So, for example, if \&a[] is declared at top level, all lower levels
  10780. will see it unless they include a "local \&a[]" statement, in which
  10781. case all levels at and beneath the level where the LOCAL statement was
  10782. executed will see the local copy. This too can be repeated to any
  10783. level.
  10784. On the other hand, if you DECLARE an array at a lower command level
  10785. without also making it LOCAL, this replaces the copy that was declared
  10786. at the lowest command level above this one.
  10787. 7.10.5. Sorting Arrays
  10788. Although arrays can be sorted using FOR loops as shown on page 383 of
  10789. Using C-Kermit, 2nd Ed., this involves quite a bit of repetitive
  10790. interpretation by the command parser, and so can be slow for large
  10791. arrays. For this reason, C-Kermit 7.0 adds a built-in SORT command:
  10792. ARRAY SORT [ switches ] array [ array2 ]
  10793. Sorts the given array in place. Sorting is strictly lexical
  10794. (string based). The array name can be given fully, e.g. "\&a[]",
  10795. or the "\" and/or "&" and/or brackets can be omitted, e.g.
  10796. "array sort \&a[]", "sort &a", "sort a". Also, a range can be
  10797. indicated in the brackets as noted in Section 7.10, to
  10798. restrict the sort to a range of elements (equivalent to the
  10799. /RANGE switch, described just below), e.g. "array sort
  10800. &a[20:30]".
  10801. A second array may be specified. If it is, and if it is at least as big
  10802. as the first array, it is sorted according to the first array. For a
  10803. sample application, see Section 7.10.10.
  10804. See Section 1.5 for an explanation of switches. The optional
  10805. switches are:
  10806. /CASE:{ON,OFF}
  10807. /CASE:ON means that alphabetic case is significant in
  10808. comparisons; uppercase letters are sorted before lowercase ones.
  10809. /CASE:OFF means case is ignored, e.g. "A" is the same as "a". If
  10810. this switch is not given, sorting is according the current SET
  10811. CASE setting.
  10812. /KEY:n
  10813. Comparison begins at position n(1-based) in each string. If no
  10814. key is given, the entire strings are compared. Only one key can
  10815. be given. If an array element is shorter than the key value, n,
  10816. that element is considered empty for comparison purposes, and
  10817. therefore lexically less than any element at least ncharacters
  10818. long.
  10819. /NUMERIC
  10820. If this switch is included, it means sorting should be numeric,
  10821. rather than lexical. The sort key is the string starting at the
  10822. key position, skipping any leading blanks or tabs, and then as
  10823. much of the string from that point on that fits the definition
  10824. of "numeric", terminating at the first character that does not
  10825. qualify. A numeric string has an optional sign (+ or -) followed
  10826. by one or more digits, and (if your version of Kermit was built
  10827. with floating-point support; see Section 7.23 ) zero or one
  10828. decimal point (period). If both /CASE and /NUMERIC are given,
  10829. /NUMERIC takes precedence.
  10830. /RANGE:n[:m]
  10831. Sort elements nthrough m of the array. By default, the entire
  10832. array from element 1 to its dimensioned size is sorted, which
  10833. might produce surprising results if the array is not full; see
  10834. example in Section 7.10.7. If ":m" is omitted from the
  10835. range, the dimensioned size is used. Thus, to sort an entire
  10836. array, \&a[], including its 0th element, use "sort /range:0 &a".
  10837. You can also sort any desired section of an array, e.g. "sort
  10838. /range:10:20 &a" or "sort /range:\%i:\%j-1 &b". As noted above,
  10839. you can also specify a range in the array-name brackets. If you
  10840. specify a range in the array-name brackets AND with a /RANGE
  10841. switch, the ones in the brackets take precedence.
  10842. /REVERSE
  10843. Sort in reverse order. If this switch is not given, the array is
  10844. sorted in ascending order.
  10845. Remember that numeric switch arguments can be numbers, arithmetic
  10846. expressions, or variables whose values are numbers or expressions, as
  10847. illustrated in the /RANGE examples above.
  10848. A typical sorting application might be to list students' test scores in
  10849. descending order. Suppose you had the following records:
  10850. olaf 65
  10851. olga 98
  10852. ivan 83
  10853. xena 100
  10854. (and so on) stored in array \&s[] (e.g. by reading them from a file as
  10855. illustrated insection 7.10.7). In these records, the student's
  10856. name is in columns 1-9 and the score in 10-12. So to rearrange the list
  10857. in descending order of score:
  10858. sort /key:10 /reverse &s
  10859. Then to list your top five students:
  10860. for \%i 1 5 1 { echo \&s[\%i] }
  10861. Or more simply (see next section):
  10862. show array a[1:5]
  10863. To illustrate the difference between a lexical and a numeric sort,
  10864. suppose you have the following records (the lines that are numbered,
  10865. starting at column 1) in array \&a[]:
  10866. Column 1 2
  10867. 12345678901234567890
  10868. 1. Ivan 10.0 2. Olaf 9.95 3. Olga 101.5
  10869. ARRAY SORT /KEY:10 &a[] would order them 3,1,2, but ARRAY SORT /KEY:10
  10870. /NUMERIC &a[] would order them 2,1,3.
  10871. 7.10.6. Displaying Arrays
  10872. The SHOW ARRAY command (or ARRAY SHOW) now accepts an optional
  10873. array-name argument:
  10874. SHOW ARRAY \&a[]
  10875. (you can leave off the \, the \&, and/or the []'s if you like; "show
  10876. array a" is equivalent to "show array \&a[]"). When an array is
  10877. specified, its dimension is shown and all defined (non-empty) elements
  10878. are listed.
  10879. Example:
  10880. assign \%n \ffiles(*,&a) ; Fill an array with filenames ( Section 4.11.3)
  10881. show array \&a[] ; Show the array we just read
  10882. array show \&a[] ; Same as previous
  10883. array sort \&a[] ; Sort the array
  10884. array show \&a[] ; Show it after sorting
  10885. array show \&a ; Show it again
  10886. array show &a ; Show it again
  10887. array show a ; Show it again
  10888. (The final four commands demonstrate the alternative forms that are
  10889. accepted for the array name.)
  10890. If you SHOW ARRAY without giving an array name, all defined arrays are
  10891. listed by name and dimension, but their contents are not shown.
  10892. You can also show a piece of an array by including a subscript or range
  10893. within the array brackets:
  10894. array show \&a[5] ; Shows \&a[5]
  10895. array show &a[3:8] ; Shows \&a[3] through \&a[8]
  10896. array show a[:\%n-1] ; Shows \&a[0] through \&a[\%n-1]
  10897. 7.10.7. Other Array Operations
  10898. ARRAY DESTROY arrayname
  10899. Destroys and undeclares the named array. Subscripts or ranges
  10900. are not accepted in this command.
  10901. ARRAY COPY array1 array2
  10902. Copies the first array to the second array. If the target array
  10903. has not been declared, it is created automatically with the same
  10904. size as the first. If it has been declared, it will be used as
  10905. declared; if the source array is larger, only as much of it as
  10906. will fit is copied to the target array. Syntax for array1 and
  10907. array2 is as in ARRAY SHOW (SHOW ARRAY). Example:
  10908. .\%n := \ffiles(*,&a) ; Create and load array A with a file list.
  10909. array copy &a &b ; Copy array A to array B.
  10910. The ARRAY COPY command also lets you copy pieces of arrays by
  10911. including range specifiers, as in these examples:
  10912. ARRAY COPY \&a[4:27] \&b
  10913. This copies \&a[] elements 4-27 to \&b[] elements 1-23,
  10914. creating \&b[] if necessary or, if \&b[] is already
  10915. declared, stopping early if its size is less than 23.
  10916. ARRAY COPY \&a[4:27] \&b[12]
  10917. This copies \&a[] elements 4-27 to \&b[] elements 12-35,
  10918. creating \&b[] if necessary or, if \&b[] is already
  10919. declared, stopping early if its size is less than 35.
  10920. ARRAY COPY \&a[4:27] \&b[12:14]
  10921. This copies \&a[] elements 4-6 to \&b[] elements 12-14,
  10922. creating \&b[] if necessary or, if \&b[] is already
  10923. declared, stopping early if its size is less than 14.
  10924. ARRAY COPY \&a[17:] \&b
  10925. This copies all the elements of \&a[] starting with 17
  10926. until the last to \&b[], creating \&b[] if necessary or,
  10927. if \&b[] is already declared, stopping early if \&b[] is
  10928. not big enough. Suppose, for example, you have a script
  10929. whose arguments are string1, string2, and a list of files,
  10930. whose job is to change all occurrences of string1 to
  10931. string2 in each of the files. But if the list of files is
  10932. omitted, then "*" (all files in the current directory) is
  10933. assumed:
  10934. if < \v(argc) 3 exit 1 "Usage: \%0 string1 string2 [ files ]"
  10935. if not def \%3 {
  10936. .n := \ffiles(*,&a)
  10937. } else {
  10938. array copy &_[3:] &a
  10939. .n := \fdim(&a)
  10940. }
  10941. for i 1 n 1 {
  10942. ! cat \&a[i] | sed -e "s|\%1|\%2|g" > /tmp/_x
  10943. rename /tmp/_x \&a[i]
  10944. }
  10945. ARRAY COPY \&a[17] \&b
  10946. Same as previous example.
  10947. ARRAY CLEAR arrayname
  10948. Sets all the elements of the array to the empty value. You may
  10949. also include a range specifier to clear only a selected portion
  10950. of the array; for example "array clear \&a[37:214]". If the
  10951. range is out of bounds, only the part of the array that is in
  10952. bounds is cleared.
  10953. ARRAY SET arrayname [ value ]
  10954. Sets all the elements of the array to the given value. If no
  10955. value is given, the array is cleared. You may also include a
  10956. range specifier to set only a selected portion of the array; for
  10957. example "array set \&a[1:9] -1". If the range is out of bounds,
  10958. only the part of the array that is in bounds is set.
  10959. ARRAY RESIZE arrayname size
  10960. Resizes the given array. If the size is greater than the array's
  10961. current dimension, new empty elements are added to the end. If
  10962. the size is less than the current dimension, the extra elements
  10963. are discarded. Note: If you have stored the array size in
  10964. element 0, ARRAY RESIZE does not change this value. Alternative
  10965. notation: ARRAY RESIZE arrayname[size]. For a practical example,
  10966. see Section 7.10.11.
  10967. \farraylook(pattern,arrayname)
  10968. This function returns the index of the first element of the
  10969. given array that matches the given pattern (for details about
  10970. pattern syntax, seesection 4.9). The array name can
  10971. include a range specification to restrict the search to a given
  10972. segment of the array. If no elements match the pattern, -1 is
  10973. returned.
  10974. \ftablelook(keyword,arrayname[,delimiter])
  10975. Looks in the given "table", which must be sorted, for the given
  10976. keyword. The keyword need not be spelled out in full.
  10977. Pattern-matching characters should not be included as part of
  10978. the keyword. The function returns the index of the table element
  10979. that uniquely matches the given keyword, or -1 if none match, or
  10980. -2 if more than 1 match.
  10981. A "table" is an array that is sorted in lexical order; each of its
  10982. elements may contain multiple fields, delimited by the given delimiter
  10983. character or, if no delimiter is specified, a colon (:).
  10984. The \farraylook() function does exactly what you tell it. If you give
  10985. it a pattern that does not include wildcard characters (such as *, ?,
  10986. etc), it requires an exact match. For example:
  10987. \farraylook(oofa,&a)
  10988. searches for the first element of \&a[] whose value is "oofa". But:
  10989. \farraylook(oofa*,&a)
  10990. finds the first element whose value starts with "oofa", and;
  10991. \farraylook(*oofa,&a)
  10992. finds the first element whose value ends with "oofa", and;
  10993. \farraylook(*oofa*,&a)
  10994. finds the first element whose value contains "oofa".
  10995. Here's a simple demonstration of looking up patterns in arrays:
  10996. local \&a[] \%x \%n
  10997. declare \&a[] = zero one two three four five six seven eight nine ten
  10998. while true {
  10999. .\%x = 1
  11000. .\%n = 0
  11001. ask \%a { Pattern? }
  11002. if not def \%a exit 0 Done.
  11003. while <= \%x \fdim(&a) {
  11004. .\%x := \farraylook(\%a,&a[\%x])
  11005. if ( < \%x 0 ) break
  11006. echo \flpad(\%x,3). \&a[\%x]
  11007. increment \%x
  11008. increment \%n
  11009. }
  11010. if ( < \%n 1 ) echo Pattern not found - "\%a"
  11011. }
  11012. The array need not be sorted. When a pattern is given, a search is
  11013. performed; if there is a match, the matching element's index and the
  11014. element itself are printed, and the search begins again at the next
  11015. element. Thus each matching element is printed. If none match, the
  11016. "Pattern not found" message is printed. The process repeats for as many
  11017. patterns as the user wants to type, and terminates when the user types
  11018. an empty pattern.
  11019. Now let's build a little command parser, consisting of a keyword table,
  11020. and a loop to look up the user's commands in it with \ftablelook(). In
  11021. this case the array elements have "fields" separated by colon (:) -- a
  11022. keyword and a value. Keyword tables must be sorted if \tablelook() is
  11023. to work right, so after declaring and initializing the table array, we
  11024. sort it.
  11025. local \&k[] \%a \%i \%n
  11026. array declare \&k[] = drive:9 do:8 discuss:7 live:6 spend:5 help:4 quit:0
  11027. array sort &k ; Make sure array is sorted
  11028. echo Type "help" for help. ; Print greeting & instructions
  11029. while true { ; Loop to get commands
  11030. undefine \%a
  11031. while not defined \%a { ; Get a command
  11032. ask \%a { Command? }
  11033. }
  11034. .\%n := \ftablelook(\%a,&k) ; Look up the command
  11035. switch \%n { ; Handle errors
  11036. :-1, echo Not found - "\%a" ; Doesn't match
  11037. continue
  11038. :-2, echo Ambiguous - "\%a" ; Matches too many
  11039. continue
  11040. }
  11041. switch \fword(\&k[\%n],2) { ; Dispatch according to value
  11042. :9, echo Driving..., break
  11043. :8, echo Doing..., break
  11044. :7, echo Discussing..., break
  11045. :6, echo Living..., break
  11046. :5, echo Spending..., break
  11047. :4, echo { Commands (may be abbreviated):}
  11048. for \%i 1 \fdim(&k) 1 {
  11049. echo { \%i. \fword(\&k[\%i],1) }
  11050. }
  11051. break
  11052. :0, exit 0 Bye!
  11053. :default, stop 1 Internal error
  11054. }
  11055. }
  11056. In this example, keywords are "drive", "do", "discuss", etc, and their
  11057. values are unique numbers (values need not be numbers, and there need
  11058. not be only one value -- there can be 0, 1, 2, or more of them). The
  11059. user types a command, which can be the whole word (like "help") or any
  11060. abbreviation (like "hel", "he", or just "h"). If this does not match
  11061. any keywords, \ftablelook() returns -1; if it matches more than one (as
  11062. would "d"), it returns -2. Otherwise the array index is returned, 1 or
  11063. higher.
  11064. Given the array index \%n, we can get the table values as follows:
  11065. \fword(\&k[\%n],1) is the keyword (first field)
  11066. \fword(\&k[\%n],2) is the value (second field, in this case a number)
  11067. In our example, we use the value (number) as the SWITCH variable. As
  11068. noted, \fablelook() expects the array elements to contain multiple
  11069. fields separated by colon (:) (or other character that you specify,
  11070. e.g. \ftablelook(\%a,&a,^)) and when matching the keyword, ignores the
  11071. first delimiter and everything after it.
  11072. 7.10.8. Hints for Using Arrays
  11073. C programmers are accustomed to out-of-bounds array references causing
  11074. core dumps or worse. In C-Kermit:
  11075. * A reference to an an out-of-bounds array element returns the empty
  11076. string.
  11077. * An attempt to set the value of an array element that is out of
  11078. bounds or that has not been declared simply fails.
  11079. C programmers expect an array of size n to have elements 0 through n-1.
  11080. Fortran programmers expect the same array to have elements 1 through n.
  11081. C-Kermit accommodates both styles; when you declare an array of size n,
  11082. it has n+1 elements, 0 through n, and you can use the array in your
  11083. accustomed manner, 0-based or 1-based.
  11084. However, note that C-Kermit has certain biases towards 1-based arrays:
  11085. * Assignment of file lists starts with element 1 (Section
  11086. 7.10.3).
  11087. * Assignment by \fsplit() starts with element 1 ( Section 7.3).
  11088. * Array initialization skips the 0th element. To initialize a 0-based
  11089. array, use something like this:
  11090. declare \&a[3] = one two three
  11091. .\&a[0] = zero
  11092. * The ARRAY SORT command skips the 0th element unless you include
  11093. /RANGE:0
  11094. * The SHIFT command ignores element 0 of the \&_[] array.
  11095. The distinction between an array's dimensioned size and the number of
  11096. elements in the array is important when sorting. To illustrate:
  11097. declare \&a[100] ; Declare array &a with 100 elements
  11098. fopen /read \%c oofa.txt ; Open a file
  11099. if fail...
  11100. for \%i 1 \fdim(&a) 1 { ; Read the file into the array
  11101. fread \%c \&a[\%i]
  11102. if fail break
  11103. }
  11104. fclose \%c
  11105. if > \%i \fdim(&a) end 1 File has too many lines for array.
  11106. .\%n ::= \%i - 1
  11107. echo File has \%n line(s).
  11108. Let's say the file had 95 lines. This leaves elements 96-100 of the
  11109. array empty. Now suppose you sort the array and write out the result:
  11110. sort &a ; Sort the whole array
  11111. fopen /write \%o oofa.txt.sorted ; Open an output file
  11112. if fail ...
  11113. for \%i 1 \%n 1 { ; Write out 95 records
  11114. fwrite /line \%o \&a[\%i]
  11115. if fail end 1 Write error
  11116. }
  11117. close write
  11118. You might be surprised at the contents of "oofa.txt.sorted" -- five
  11119. empty elements, 96-100, floated to the top of the array in the sort,
  11120. and since your write loop only had 95 iterations, the final 5 lines of
  11121. the sorted file are lost.
  11122. Therefore, when dealing with partially filled arrays -- especially when
  11123. sorting them -- remember to specify the number of elements. A handy way
  11124. of recording an array's "true" size is to put it in the 0th element.
  11125. That way, it "travels with the array". To illustrate (continuing the
  11126. previous example at the "close read" statement):
  11127. close read
  11128. if > \%i \fdim(&a) end 1 File has too many lines for array.
  11129. .\&a[0] ::= \%i - 1 ; Assign number of lines to \&a[0].
  11130. echo File has \&a[0] line(s).
  11131. sort /range:1:\&a[0] &a
  11132. open write oofa.txt.sorted
  11133. if fail ...
  11134. for \%i 1 \&a[0] 1 {
  11135. writeln file \&a[\%j]
  11136. if fail end 1 Write error
  11137. }
  11138. close write
  11139. Note the SORT switch, /RANGE:1:\&a[0]. This keeps the sort 1-based, and
  11140. uses element 0 of the array as its size indicator.
  11141. Finally, note that even though some commands or functions might put a
  11142. size in array element 0, no built-in functions or commands depend on a
  11143. size actually being there. Thus you are perfectly free to replace the
  11144. size with something else and treat the array as 0-based.
  11145. 7.10.9. Do-It-Yourself Arrays
  11146. Kermit's \&x[] arrays are nice because of the accompanying built-in
  11147. functionality -- ARRAY commands, built-in functions that load and
  11148. search arrays, automatic evaluation of arithmetic expressions within
  11149. the subscript brackets, and so on. Yet they also have certain
  11150. limitations:
  11151. 1. Except when created by dynamic loading (e.g. by \ffiles()) they
  11152. must be declared and dimensioned in advance.
  11153. 2. Indices must be numeric, positive, and in range.
  11154. 3. There can be only one dimension. Matrices or other
  11155. higher-dimensioned arrays are not available.
  11156. But none of this is to say you can't invent any kind of data structure
  11157. you like. In Section 7.9.2 you can see some examples. Here's
  11158. another (courtesy of Dat Thuc Nguyen), in which a pair of matrices is
  11159. created and then added: no dimensioning necessary.
  11160. .row = 4
  11161. .col = 9
  11162. ; MACRO TO PRINT A MATRIX
  11163. define PMATRIX {
  11164. echo Matrix \%1:
  11165. for \%r 1 \m(row) 1 {
  11166. for \%c 1 \m(col) 1 {
  11167. xecho \flpad(\m(\%1[\%r][\%c]),4)
  11168. }
  11169. echo
  11170. }
  11171. echo
  11172. }
  11173. ; CREATE MATRICES A AND B
  11174. for \%r 1 \m(row) 1 {
  11175. for \%c 1 \m(col) 1 {
  11176. _eval A[\%r][\%c] \%r + \%c
  11177. _eval B[\%r][\%c] \%r * \%c
  11178. }
  11179. }
  11180. ; CREATE MATRIX C = SUM OF MATRIX A AND MATRIX B
  11181. for \%r 1 \m(row) 1 {
  11182. for \%c 1 \m(col) 1 {
  11183. _eval C[\%r][\%c] \m(A[\%r][\%c]) + \m(B[\%r][\%c])
  11184. }
  11185. }
  11186. pmatrix A ; Print Matrix A
  11187. pmatrix B ; Print Matrix B
  11188. pmatrix C ; Print Matrix C
  11189. In the example, we use matrix-like notation to create macros with names
  11190. like "A[1][1]", "B[3][7]", and so on.
  11191. 7.10.10. Associative Arrays
  11192. An associative array is a special kind of Do-It-Yourself array. It
  11193. differs from a regular array in that its indices need not be numbers --
  11194. they can be anything at all -- words, filenames, names of months, any
  11195. character string at all, and that it doesn't have to be (and in fact
  11196. can't be) declared. An associative array element is simply a macro
  11197. whose name ends with an index enclosed in angle brackets, for example:
  11198. file<oofa.txt>
  11199. More formally:
  11200. basename<index>
  11201. An associative array is a collection of all associative array elements
  11202. that have the same basename. Any number of associative arrays, each
  11203. with any number of elements, can exist at the same time.
  11204. An associative array element can be assigned a value, such as "1", just
  11205. like any other macro:
  11206. define file<oofa.txt> 1 ; Give "file<oofa.txt>" the value "1".
  11207. or:
  11208. assign file<oofa.txt> \%a ; Give it the value of the variable \%a.
  11209. However, since an associative array element is a macro, it may not have
  11210. an empty (null) value, since assigning an empty value to a macro
  11211. undefines the macro.
  11212. You can refer to the value of an associative array element using the
  11213. familiar notation for macro values:
  11214. echo \m(file<oofa.txt>) ; Echo the value of "file<oofa.txt>".
  11215. Associative arrays are most useful, however, when the value of the
  11216. index is a variable. In that case, you must use the "hidden" forms of
  11217. the DEFINE or ASSIGN commands that evaluate the macro name before
  11218. making the assignment (seeUsing C-Kermit, page 457). Example:
  11219. define \%f oofa.txt
  11220. _define file<\%f> 1
  11221. echo file<\%f> = \m(file<\%f>)
  11222. prints:
  11223. file<oofa.txt> = 1
  11224. and then:
  11225. _increment file<\%f>
  11226. echo file<\%f> = \m(file<\%f>)
  11227. prints:
  11228. file<oofa.txt> = 2
  11229. What are associative arrays good for? The classic example is "word
  11230. counts": finding the number of times each word is used in a text
  11231. without knowing in advance what the words are. Without associative
  11232. arrays, your program would have to build a table of some kind, and
  11233. every time a word was encountered, look it up in the table to find its
  11234. position and counter, or add it to the table if it wasn't found -- a
  11235. time-consuming and laborious process. Associative arrays, however, let
  11236. you use the word itself as the table index and therefore sidestep all
  11237. the table building and lookups.
  11238. Let's work through a practical example. Suppose you have a
  11239. file-transfer log in which each line is composed of a number of
  11240. blank-separated fields, and the 9th field is a filename (which happens
  11241. to be the format of certain FTP server logs, as well as of C-Kermit's
  11242. new FTP-format transaction log, described in Section 4.17.2), for
  11243. example:
  11244. Wed Jul 14 09:35:31 1999 22 xx.mit.edu 13412 /pub/ftp/mm/intro.txt ....
  11245. and you want to find out how many times each file was transferred. The
  11246. following code builds an associative array, file<>, containing the
  11247. counts for each file:
  11248. local name line max \%c \%n ; Declare local variables
  11249. fopen /read \%c /var/log/ftpd.log ; Open the log file ( Section 1.22)
  11250. if fail exit 1 Can't open log ; Check
  11251. while true { ; Loop for each record
  11252. fread /line \%c line ; Read a line
  11253. if fail break ; Check for end of file
  11254. .name := \fword(\m(line),9,{ }) ; Get 9th field = filename (Sec 7.3)
  11255. _increment file<\m(name)> ; Increment its counter (Sec 7.9.2)
  11256. }
  11257. fclose \%c ; Close file when done.
  11258. Note that _INCREMENT (and INCREMENT, and [_]DECREMENT) treat an empty
  11259. (i.e. nonexistent) variable as having a value of 0, and therefore
  11260. creates the variable with a value of 1.
  11261. At this point, if you told Kermit to "show macro file<", it would list
  11262. the associative array. But since you don't necessarily know the names
  11263. of the files in the array, or even how many elements are in the array,
  11264. how can you use it in a script program?
  11265. The idea of creating macro names that include character-string indices
  11266. enclosed in angle brackets is perfectly arbitrary and doesn't depend on
  11267. any Kermit features that weren't already there -- we could just as
  11268. easily have used some other notation, such as "file[index]",
  11269. "file:index", or "file.index", and the code above would have worked
  11270. just as well (with the corresponding syntax adjustments). But to be
  11271. able to use an associative array in a program after the array is built,
  11272. we need a method of accessing all its elements without knowing in
  11273. advance what they are. That's where the chosen notation comes in.
  11274. First of all, any macro name that ends with "<xxx>" (where "xxx" is any
  11275. string) is case sensitive, unlike all other macro names, which are case
  11276. independent. To illustrate, "file<oofa.txt>" and "file<OOFA.TXT>" are
  11277. two distinct macros, whereas "OOFA", "Oofa", and "oofa", when used as
  11278. macro names, are all the same.
  11279. Second, the new \faaconvert() function converts an associative array
  11280. (that is, all macros with names of the form "base<index>" that have the
  11281. same "base" part) into a pair of regular arrays and returns the number
  11282. of elements:
  11283. \faaconvert(name,&a[,&b])
  11284. "name" is the name of the associative array, without the angle brackets
  11285. or index ("file" in our example).
  11286. The second argument is the name of a regular array in which to store
  11287. the indices of the associative array (filenames in our example); if an
  11288. array of this name already exists, it is destroyed unless the array is
  11289. LOCAL. The third argument is the name of another regular array in which
  11290. to store the values (the counts in our example), with the same rules
  11291. about array name collisions. If you care only about the indices and not
  11292. the values, you can omit the third argument to \faaconvert(). In any
  11293. case, the associative array is converted, not copied: its elements are
  11294. moved to the specified regular arrays, so after conversion the original
  11295. associative array is gone.
  11296. As with other array-loading functions, \faaconvert() sets element 0 of
  11297. each array to the number of elements in the array.
  11298. To continue our example:
  11299. .max := 0 ; Maximum count
  11300. .\%n := \faaconvert(file,&a,&b) ; Convert
  11301. for \%i 1 \%n 1 { ; Loop through values
  11302. echo \flpad(\%i,3). \&a[\%i]: \&b[\%i] ; Echo this pair
  11303. if ( > \&b[\%i] \m(max) ) { ; Check for new maximum
  11304. .name := \&a[\%i]
  11305. .max := \&b[\%i]
  11306. }
  11307. }
  11308. echo Most popular file: \m(name), accesses: \m(max)
  11309. This lists the files and counts and then announces which file has the
  11310. highest count.
  11311. Now suppose you want to sort the array pair created from an associative
  11312. array. In our example, \&a[] contains filenames, and \&b[] contains the
  11313. associated counts. Here we take advantage of the ARRAY SORT command's
  11314. ability to sort a second array according to the first one:
  11315. array sort /reverse /numeric &b &a ; Descending sort by count
  11316. Now to see the top five files and their counts:
  11317. echo The top 5 files are:
  11318. for \%i 1 5 1 { ; Loop through top 5 values
  11319. echo \flpad(\%i,3). \&a[\%i]: \&b[\%i] ; Echo this pair
  11320. }
  11321. 7.10.11. Transferring Array Contents to Other Computers
  11322. The SEND /ARRAY:arrayname command ( Section 4.7.1) allows you to
  11323. send the contents of any array, or any contiguous segment of it, in
  11324. either text or binary mode to another computer, using Kermit protocol.
  11325. When used in conjunction with C-Kermit's other features (the array
  11326. features described in this section; the file i/o package from
  11327. Section 1.22; its decision-making, pattern-matching, and string
  11328. manipulation capabilities, and so on) the possibilities are endless:
  11329. extracts of large files, remote database queries, ..., all without
  11330. recourse to system-dependent mechanisms such UNIX pipes and filters,
  11331. thus ensuring cross-platform portability of scripts that use these
  11332. features.
  11333. When sending an array in text mode, Kermit appends a line terminator to
  11334. each array element, even empty ones, and it also converts the character
  11335. set from your current FILE character-set to your current TRANSFER
  11336. character-set, if any. No conversions are made or line terminations
  11337. added in binary mode. For example, the following array:
  11338. dcl \&a[] = One Two Three Four Five Six
  11339. is sent as six lines, one word per line, in text mode, and as the bare
  11340. unterminated string "OneTwoThreeFourFiveSix" in binary mode.
  11341. You should always include a /TEXT or /BINARY switch in any SEND /ARRAY
  11342. command to force the desired transfer mode, otherwise you're likely to
  11343. be surprised by the effects described in Section 4.3.
  11344. Here are some examples:
  11345. send /text /array:\&a[]
  11346. Sends the entire contents of the array \&a[] in text mode. Since
  11347. an as-name is not included, the receiver is told the filename is
  11348. _array_a_.
  11349. send /text /array:&a[]
  11350. send /text /array:a[]
  11351. send /text /array:&a
  11352. send /text /array:a
  11353. These are all equivalent to the previous example.
  11354. send /text /array:&a /as-name:foo.bar
  11355. As above, but the array is sent under the name foo.bar.
  11356. send /text /array:&a[100:199] /as:foo.bar
  11357. As above, but only the elements from 100 through 199 are sent.
  11358. In text-mode transfers, character sets are translated according to your
  11359. current settings, just as for text files. In binary mode, of course,
  11360. there is no character-set translation or other conversion of any kind.
  11361. But remember that array elements can not contain the NUL (ASCII 0)
  11362. character, since they are implemented as NUL-terminated strings.
  11363. Here's an example that shows how to send all the lines (up to 1000 of
  11364. them) from a file animals.txt that contain the words "cat", "dog", or
  11365. "hog" (see Section 4.9 about pattern matching):
  11366. declare \&a[1000]
  11367. fopen /read \%c animals.txt
  11368. if fail exit 1
  11369. .\%i = 0
  11370. while true {
  11371. fread \%c line
  11372. if fail break
  11373. if match {\m(line)} {*{cat,[dh]og}*} {
  11374. increment \%i
  11375. if ( > \%i \fdim(&a) ) break
  11376. .\&a[\%i] := \m(line)
  11377. }
  11378. }
  11379. fclose \%c
  11380. send /array:a[1:\%i] /text
  11381. Note that we are careful to send only the part of the array that was
  11382. filled, not the entire array, because there are likely to be lots of
  11383. unused elements at the end, and these would be sent as blank lines
  11384. otherwise.
  11385. This example raises an interesting question: what if we want to send
  11386. ALL the matching lines, even if there are more than 1000 of them, but
  11387. we don't know the number in advance? Clearly the problem is limited by
  11388. Kermit's (and the computer's) memory. If there are a thousand trillion
  11389. matching lines, they most likely will not fit in memory, and in this
  11390. case the only solution is to write them first to a temporary file on
  11391. mass storage and then send the temporary file and delete it afterwards.
  11392. However, when the selection is likely to fit in memory, the
  11393. once-familiar technique of initial allocation with extents can be used:
  11394. if match {\m(line)} {*{cat,[dh]og}*} {
  11395. increment \%i
  11396. if ( > \%i \fdim(&a) ) {
  11397. array resize a \fdim(&a)+100
  11398. if fail stop 1 MEMORY FULL
  11399. echo NEW DIMENSION: \fdim(&a)
  11400. }
  11401. .\&a[\%i] := \m(line)
  11402. }
  11403. This grows the array in chunks of 100 as needed.
  11404. 7.11. OUTPUT Command Improvements
  11405. LINEOUT [ text ]
  11406. This command is exactly like OUTPUT, except it supplies a
  11407. carriage return at the end of the text. "lineout exit" is
  11408. exactly the same as "output exit\13".
  11409. SET OUTPUT SPECIAL-ESCAPES { ON, OFF }
  11410. This command lets you tell C-Kermit whether to process \N, \L,
  11411. and \B specially in an OUTPUT command, as distinct from other \
  11412. sequences (such as \%a, \13, \v(time), etc). Normally the
  11413. special escapes are handled. Use SET OUTPUT SPECIAL-ESCAPES OFF
  11414. to disable them.
  11415. Disabling special escapes is necessary in situations when you need to
  11416. transmit lines of data and you have no control over what is in the
  11417. lines. For example, a file oofa.txt that contains:
  11418. This is a file
  11419. It has \%a variables in it
  11420. And it has \B in it.
  11421. And it has \L in it.
  11422. And it has \N in it.
  11423. And this is the last line.
  11424. can be sent like this:
  11425. local line
  11426. set output special-escapes off
  11427. fopen /read \%c oofa.txt
  11428. if fail stop 1 Can't open oofa.txt
  11429. while success {
  11430. fread \%c line
  11431. if fail break
  11432. ; Add filtering or processing commands here...
  11433. output \m(line)\13
  11434. }
  11435. 7.12. Function and Variable Diagnostics
  11436. In C-Kermit 6.0 and earlier, the only diagnostic returned by a failing
  11437. function call was an empty value, which (a) could not be distinguished
  11438. from an empty value returned by a successful function call; (b) did not
  11439. give any indication of the cause of failure; and (c) did not cause the
  11440. enclosing statement to fail. C-Kermit 7.0 corrects these deficiencies.
  11441. SET FUNCTION DIAGNOSTICS { ON, OFF }
  11442. when ON, allows built-in functions to return diagnostic messages
  11443. when improperly referenced, instead of an empty string. FUNCTION
  11444. DIAGNOSTICS are ON by default. When OFF, improperly referenced
  11445. functions continue to return an empty string. This command also
  11446. affects built-in variables; in this case, an error message is
  11447. returned only if the variable does not exist. When FUNCTION
  11448. DIAGNOSTICS are ON, the error message is also printed.
  11449. For variables, the only message is:
  11450. <ERROR:NO_SUCH_VARIABLE:\v(name)>
  11451. where "name" is the name of the nonexistent variable.
  11452. For functions, the diagnostic message is:
  11453. <ERROR:message:\fname()>
  11454. where "message" is replaced by a message, and "name" is replaced by the
  11455. function name, e.g. <ERROR:ARG_NOT_NUMERIC:\fmod()>. Messages include:
  11456. ARG_BAD_ARRAY An argument contains a malformed array reference.
  11457. ARG_BAD_DATE An argument contains a malformed date and/or time.
  11458. ARG_BAD_PHONENUM An argument contains a malformed telephone number.
  11459. ARG_BAD_VARIABLE An argument contains a malformed \%x variable.
  11460. ARG_INCOMPLETE An argument is incomplete (e.g. a broken Base64 string).
  11461. ARG_EVAL_FAILURE An argument could not be evaluated (internal error).
  11462. ARG_NOT_ARRAY An argument references an array that is not declared.
  11463. ARG_NOT_NUMERIC An argument that must be integer contains non-digits.
  11464. ARG_NOT_FLOAT An argument has bad floating-point number format.
  11465. ARG_NOT_VARIABLE An argument that must be a variable is not a variable.
  11466. ARG_OUT_OF_RANGE An argument's numeric value is too big or too small,
  11467. or an argument contains illegal characters (e.g. a hex
  11468. or Base-64 string).
  11469. ARG_TOO_LONG An argument's value is too long.
  11470. ARRAY_FAILURE Failure to create an array.
  11471. DIVIDE_BY_ZERO Execution of the function would cause division by zero.
  11472. FLOATING_POINT_OP Execution error in a floating-point operation.
  11473. FILE_NOT_FOUND Filename argument names a file that can't be found.
  11474. FILE_NOT_READABLE Filename argument is not a regular file.
  11475. FILE_NOT_ACCESSIBLE Filename argument names a file that is read-protected.
  11476. FILE_ERROR Other error with filename argument.
  11477. FILE_NOT_OPEN A file function was given a channel that is not open.
  11478. FILE_ERROR_-n A file function got error -n ( Section 1.22).
  11479. LOOKUP_FAILURE Error looking up function (shouldn't happen).
  11480. MALLOC_FAILURE Failure to allocate needed memory (shouldn't happen).
  11481. NAME_AMBIGUOUS The function is not uniquely identified.
  11482. MISSING_ARG A required argument is missing.
  11483. NO_SUCH_FUNCTION An argument references a function that is not defined.
  11484. NO_SUCH_MACRO An argument references a macro that is not defined.
  11485. RESULT_TOO_LONG The result of a function is too long.
  11486. UNKNOWN_FUNCTION Internal error locating function (shouldn't happen).
  11487. Examples:
  11488. assign \%m \fmod()
  11489. ?<ERROR:MISSING_ARG:\fmod()>
  11490. echo "\fcontents(\%m)"
  11491. "<ERROR:MISSING_ARG:\fmod()>"
  11492. echo \fmod(3,x)
  11493. ?<ERROR:ARG_NOT_NUMERIC:\fmod()>
  11494. echo \fmod(3,4-2*2)
  11495. ?<ERROR:DIVIDE_BY_ZERO:\fmod()>
  11496. Notice the use of \fcontents() in echoing the value of a variable that
  11497. contains a returned error message. That's because the error message
  11498. includes the name of the variable or function that failed, so you must
  11499. use \fcontents() to prevent it from being evaluated again -- otherwise
  11500. the same error will occur.
  11501. The handling of function and variable errors is controlled by:
  11502. SET FUNCTION ERROR { ON, OFF }
  11503. Tells whether invalid function calls or variable references
  11504. should cause command errors. FUNCTION ERROR is ON by default.
  11505. When ON, and an error is diagnosed in a built-in function or
  11506. variable, the command that includes the function call or
  11507. variable reference fails. The failing command can be handled in
  11508. the normal way with IF FAILURE / IF SUCCESS, SET TAKE ERROR, or
  11509. SET MACRO ERROR.
  11510. When FUNCTION DIAGNOSTICS is OFF, there is no error message.
  11511. SHOW SCRIPTS displays the current FUNCTION DIAGNOSTICS and ERROR
  11512. settings.
  11513. 7.13. Return Value of Macros
  11514. In C-Kermit 5A and 6.0, there are two ways to return one level from a
  11515. macro: RETURN value and END number text. When RETURN is used, the
  11516. value, which can be a number or a text string, is assigned to
  11517. \v(return). When END was used, however, \v(return) was not set.
  11518. SUCCESS/FAILURE was set according to whether the number was zero, and
  11519. the text was printed, but the actual value of the number was lost.
  11520. In C-Kermit 7.0, the END number is available in the \v(return)
  11521. variable.
  11522. 7.14. The ASSERT, FAIL, and SUCCEED Commands.
  11523. The ASSERT command is just like the IF command, but without a command
  11524. to execute. It simply succeeds or fails, and this can be tested by a
  11525. subsequent IF SUCCESS or IF FAILURE command. Example:
  11526. ASSERT = 1 1
  11527. IF SUCCESS echo 1 = 1.
  11528. The FAIL command does nothing, but always fails. The SUCCEED command
  11529. does nothing, but always succeeds.
  11530. These commands are handy in debugging scripts when you want to induce a
  11531. failure (or success) that normally would not occur, e.g. for testing
  11532. blocks of code that normally are not executed.
  11533. 7.15. Using Alarms
  11534. Alarms may be set in two ways:
  11535. SET ALARM number
  11536. Sets an alarm for the given number of seconds "from now", i.e.
  11537. in the future, relative to when the SET ALARM command was given.
  11538. Examples:
  11539. set alarm 60 ; 60 seconds from now
  11540. set alarm +60 ; The same as "60"
  11541. set alarm -60 ; Not legal - you can't set an alarm in the past.
  11542. set alarm 60*60 ; 60 minutes from now.
  11543. set alarm \%a+10 ; You can use variables, etc.
  11544. SET ALARM hh:mm:ss
  11545. Sets an alarm for the specified time. If the given time is
  11546. earlier than the current time, the alarm is set for the given
  11547. time in the next day. You may give the time in various formats:
  11548. set alarm 15:00:00 ; 3:00:00pm
  11549. set alarm 3:00:00pm ; 3:00:00pm
  11550. set alarm 3:00pm ; 3:00:00pm
  11551. set alarm 3pm ; 3:00:00pm
  11552. SHOW ALARM
  11553. Displays the current alarm, if any, in standard date-time format
  11554. (see Section 1.6): yyyymmdd hh:mm:ss.
  11555. IF ALARM command
  11556. Executes the command if an alarm has been set and the alarm time
  11557. has passed.
  11558. IF ALARM { command-list } [ ELSE { command-list } ]
  11559. Executes the command-list if an alarm has been set and the alarm
  11560. time has passed. Otherwise, if an ELSE part is given, its
  11561. command-list is executed.
  11562. CLEAR ALARM
  11563. Clears the alarm.
  11564. Only one alarm may be set at a time.
  11565. Example: Suppose you have a script that is always running, and that
  11566. transfers files periodically, and that keeps a transaction log. Suppose
  11567. you want to start a new transaction log each day:
  11568. log transactions \v(date).log
  11569. set alarm 00:00:00 ; Set an alarm for midnight
  11570. while true { ; Main script loop
  11571. xif alarm { ; If the alarm time is past...
  11572. close transactions ; Close current log
  11573. log transactions \v(date).log ; Start new one
  11574. pause 1 ; To make sure 00:00:00 is past
  11575. set alarm 00:00:00 ; Set a new alarm
  11576. }
  11577. ; put the rest of the script here...
  11578. }
  11579. Note that IF ALARM -- no matter whether it succeeds or fails -- does
  11580. NOT clear an expired alarm. Thus, once an alarm has expired, every IF
  11581. ALARM will succeed until the alarm is cleared (with the CLEAR ALARM
  11582. command) or reset with a new SET ALARM command.
  11583. 7.16. Passing Arguments to Command Files
  11584. Beginning in version 7.0, C-Kermit accepts arguments on the TAKE
  11585. command line, for example:
  11586. C-Kermit> take oofa.ksc one two {this is three} four
  11587. This automatically sets the variables \%1 through \%9 to the arguments,
  11588. and \%0 to the name of the file, in this case:
  11589. \%0 = /usr/olga/oofa.ksc
  11590. \%1 = one
  11591. \%2 = two
  11592. \%3 = this is three
  11593. \%4 = four
  11594. and \%5..\%9 are undefined (empty). Arguments past the ninth are
  11595. available in the \&_[] argument-vector array ( Section 7.5).
  11596. The variables are those at the current macro level. Thus, if the TAKE
  11597. command is executed from within a macro, the macro's arguments are
  11598. replaced by those given on the TAKE command line (but only if at least
  11599. one argument is given). The command shown above is exactly equivalent
  11600. to:
  11601. assign \%0 /usr/olga/oofa.ksc
  11602. assign \%1 one
  11603. assign \%2 two
  11604. assign \%3 this is three
  11605. assign \%4 four
  11606. assign \%5
  11607. assign \%6
  11608. assign \%7
  11609. assign \%8
  11610. assign \%9
  11611. take oofa.ksc
  11612. Remember, the variables \%0..\%9 are on the macro call stack, and
  11613. command files are independent of the macro stack. Thus, if a command
  11614. file TAKEs another command file and passes arguments to it, the
  11615. variables are changed from that point on for both files, and so forth
  11616. for all levels of nested command files without intervening macro
  11617. invocations.
  11618. It would have been possible to change C-Kermit to use the overall
  11619. command stack, rather than the macro stack, for arguments -- this would
  11620. have made TAKE work exactly like DO, which is "nicer", but it would
  11621. also have broken countless existing scripts. However, the new SHIFT
  11622. command ( Section 7.5) makes it possible to create an alternative
  11623. TAKE command that does indeed save and restore the argument variables
  11624. at its own level around execution of a command file:
  11625. define mtake {
  11626. local \%f
  11627. assign \%f \fcontents(\%1)
  11628. shift
  11629. take \%f
  11630. }
  11631. C-Kermit 7.0 also supports a new, easier way to pass arguments to
  11632. scripts from the system command line:
  11633. kermit filename arg1 arg2 arg3 ...
  11634. in which arg1, arg2, arg3 (etc) are arguments for the script (whose
  11635. filename is given), and are assigned to \%1, \%2, ... \%9. The filename
  11636. is assigned to \%0. This applies equally to "Kerbang" scripts in UNIX
  11637. ( Section 7.19). For example, suppose you have a file called
  11638. "showargs" containing the following lines:
  11639. #!/usr/local/bin/kermit +
  11640. echo Hello from \%0
  11641. show args
  11642. exit
  11643. (except not indented, since the "#!" line must be on the left margin).
  11644. If you give this file execute permission:
  11645. chmod +x showargs
  11646. then you can run it exactly as you would run a UNIX shell script, e.g.:
  11647. $ showargs one two three
  11648. Hello from /usr/olga/showargs
  11649. Top-level arguments (\v(argc) = 4):
  11650. \&_[0] = /usr/olga/showargs
  11651. \&_[1] = one
  11652. \&_[2] = two
  11653. \&_[3] = three
  11654. Furthermore, the \&_[] array now contains the filename, if one was
  11655. given as the first command line argument, or it is a "Kerbang" script,
  11656. in element 0.
  11657. Otherwise element 0 is program name, and elements 1 through \v(argc)-1
  11658. contain the command-line arguments, if any, that appear after "--" or
  11659. "=", if any. This array is saved and restored around macro calls;
  11660. recall that inside macros it contains the macro argument vector
  11661. (allowing you to access arguments programmatically, and to have more
  11662. than 9 of them).
  11663. At top level, notice the difference between the \&@[] and \&_[] arrays.
  11664. The former includes C-Kermit options; the latter omits them.
  11665. 7.17. Dialogs with Timed Responses
  11666. The ASK, ASKQ, GETOK, and GETC commands (let's call them the "ASK-class
  11667. commands") let you write scripts that carry on dialogs with the user,
  11668. asking them for text, a Yes/No answer, or a character, respectively.
  11669. Prior to C-Kermit 7.0, these questions would always wait forever for an
  11670. answer. In C-Kermit 7.0, you may specify a time limit for them with the
  11671. new command:
  11672. SET ASK-TIMER number
  11673. Sets a time-limit on ASK-CLASS commands to the given number of
  11674. seconds. If the number is 0 or less, there is no time limit and
  11675. these commands wait forever for a response. Any timer that is
  11676. established by this command remains in effect for all future
  11677. ASK-class commands until another SET ASK-TIMER command is given
  11678. (e.g. with a value of 0 to disable ASK timeouts).
  11679. IF ASKTIMEOUT command
  11680. An ASK-class command that times out returns a failure status.
  11681. You can test explicitly for a timeout with:
  11682. 7.18. Increased Flexibility of SWITCH Case Labels
  11683. Prior to C-Kermit 7.0 / K95 1.1.19, the case labels in SWITCH
  11684. statements were string constants.
  11685. Now case labels can be variables, function calls, or any mixture of
  11686. these with each other and/or with regular characters.
  11687. Furthermore, after the case label is evaluated, it is treated not as a
  11688. string constant, but as a pattern against which the SWITCH variable is
  11689. matched ( Section 4.9.1).
  11690. This introduces a possible incompatibility with previous releases,
  11691. since the following characters in case labels are no longer taken
  11692. literally:
  11693. \ * ? [ {
  11694. Any scripts that previously included any of these characters in case
  11695. labels must now quote them with backslash (\).
  11696. 7.19. "Kerbang" Scripts
  11697. In UNIX only, Kermit scripts can be stored in files and run "directly",
  11698. without starting Kermit first (as noted on page 467 of the manual),
  11699. just as a shell script can be "run" as if it were a program. This
  11700. section amplifies on that idea a bit, and presents some new aspects of
  11701. version 7.0 that make it easier to write and run Kermit scripts
  11702. directly.
  11703. NOTE: On non-UNIX platforms, such as VMS or Windows, Kerbang scripts
  11704. can be run as "kermit + scriptfilename arg1 arg2 arg3 ...". Windows
  11705. 95/98/NT file associations do not allow for the passing of
  11706. parameters. In VMS, however, you can achieve the Kerbang effect by
  11707. defining a symbol, as in this example:
  11708. $ autotelnet :== "$SYS$TOOLS:KERMIT.EXE + AUTOTELNET.KSC"
  11709. and then running the script like any other command:
  11710. $ autotelnet xyzcorp.com myuserid
  11711. See Section 9.3 for an explanation of the "+" symbol.
  11712. UNIX shell scripts can specify which shell should run them by including
  11713. a "shebang" line at the top, e.g.:
  11714. #!/bin/sh
  11715. (but not indented; the shebang line must be on the left margin). The
  11716. term "shebang" is a contraction of "shell" and "bang". "Bang" is a
  11717. slang word for the exclamation mark ("!"); "shebang" itself is an
  11718. American slang word used in in the phrase "the whole shebang".
  11719. We can run Kermit scripts directly too, by including a "shebang" line
  11720. that names Kermit as the "shell"; thus we call these "Kerbang" scripts.
  11721. This mechanism has been considerably simplified in C-Kermit 7.0 to
  11722. facilitate C-Kermit's use a scripting tool just like any of the UNIX
  11723. shells or scripting languages. The rules are the same as for shell
  11724. scripts:
  11725. 1. The first line of the Kermit script must begin with "#!"
  11726. immediately followed by the full pathname of the program that will
  11727. execute the script (in this case, C-Kermit rather than a UNIX
  11728. shell), followed by any Kermit command-line options. To suppress
  11729. execution of the C-Kermit initialization file and to make command
  11730. line arguments available to the script, the final option should be
  11731. "+":
  11732. #!/usr/local/bin/kermit +
  11733. Some users have reported that in some circumstances a space might
  11734. be necessary after the plus sign; this depends on your shell -- it
  11735. has nothing to do with Kermit. In most cases, no space is needed.
  11736. 2. The file must have execute permission (granted via "chmod +x
  11737. filename").
  11738. When C-Kermit is invoked from a Kerbang script (or from the system
  11739. prompt with a "+" command-line argument, which amounts to the same
  11740. thing), the following special rules apply:
  11741. 1. The C-Kermit initialization file is NOT executed automatically. If
  11742. you want it to be executed, include a TAKE command for it in the
  11743. script, e.g. "take \v(home).kermrc". (In previous releases, the
  11744. initialization file was always executed, with no way to prevent it
  11745. except for the user to include Kermit-specific command line options
  11746. which had nothing to do with the script). Many scripts have no need
  11747. for the standard Kermit initialization file, which is quite lengthy
  11748. and not only delays startup of the script, but also spews forth
  11749. numerous messages that are most likely unrelated to the script.
  11750. 2. If the initialization file is not executed, neither is your
  11751. customization file, since the initialization file is the command
  11752. file from which the customization file is TAKEn. Again, you can
  11753. include a TAKE command for the initialization file if desired, or
  11754. for the customization file by itself, or for any other file.
  11755. 3. C-Kermit does not process command-line arguments at all. Instead,
  11756. it passes all words on the command line after the "+" to the script
  11757. as \%0 (the script name), \%1..\%9 (the first nine arguments), as
  11758. well as in the argument vector array \&_[]. The variable \v(argc)
  11759. is set to the total number of "words" (as passed by the shell to
  11760. Kermit) including the script name. Quoting and grouping rules are
  11761. those of the shell.
  11762. 4. At any point where the script terminates, it must include an EXIT
  11763. command if you want it to exit back to the shell; otherwise
  11764. C-Kermit enters interactive prompting mode when the script
  11765. terminates. The EXIT command can include a numeric status to be
  11766. returned to the shell (0, 1, etc), plus an optional message.
  11767. Here is a simple Kerbang script that prints its arguments:
  11768. #/usr/local/bin/kermit +
  11769. echo Hello from \%0
  11770. for \%i 0 \v(argc)-1 1 {
  11771. echo \%i. "\&_[\%i]"
  11772. }
  11773. exit 0
  11774. Save this file as (say) "showargs", then give it execute permission and
  11775. run it (the \&_[] array is the same as \%0..\%9, but allows you to
  11776. refer to argument variables programmatically; see Section 7.5).
  11777. (Yes, you could substitute SHOW ARGUMENTS for the loop.)
  11778. $ chmod +x showargs
  11779. $ ./showargs one "this is two" three
  11780. The script displays its arguments:
  11781. Hello from /usr/olga/showargs
  11782. 0. "/usr/olga/showargs"
  11783. 1. "one"
  11784. 2. "this is two"
  11785. 3. "three"
  11786. $
  11787. Notice that no banners or greetings are printed and that startup is
  11788. instantaneous, just like a shell script. Also notice that grouping of
  11789. arguments is determined by *shell* quoting rules, not Kermit ones,
  11790. since the command line is parsed by the shell before Kermit ever sees
  11791. it.
  11792. Of course you can put any commands at all into a Kerbang script. It can
  11793. read and write files, make connections, transfer files, anything that
  11794. Kermit can do -- because it *is* Kermit. And of course, Kerbang scripts
  11795. can also be executed from the Kermit prompt (or from another script)
  11796. with a TAKE command; the Kerbang line is ignored since it starts with
  11797. "#", which is a comment introducer to Kermit just as it is to the UNIX
  11798. shell. In VMS and other non-UNIX platforms, the Kerbang line has no
  11799. effect and can be omitted.
  11800. It might be desirable for a script to know whether it has been invoked
  11801. directly from the shell (as a Kerbang script) or by a TAKE command
  11802. given to the Kermit prompt or in a Kermit command file or macro. This
  11803. can be done as in this example:
  11804. #!/usr/local/bin/kermit +
  11805. assign \%m \fbasename(\%0)
  11806. define usage { exit 1 {usage: \%m phonenumber message} }
  11807. define apage { (definition of APAGE...) } ; (Seebook pp.454-456)
  11808. xif equal "\%0" "\v(cmdfil)" {
  11809. if not def \%1 usage
  11810. if not def \%2 usage
  11811. apage {\%1} {\%2}
  11812. exit \v(status)
  11813. }
  11814. In a Kerbang script, \%0 and \v(cmdfile) are the same; both of them are
  11815. the name of the script. When a script is invoked by a Kermit TAKE
  11816. command, \%0 is the name of the Kermit program, but \v(cmdfile) is the
  11817. name of the script. In the example above, a macro called APAGE is
  11818. defined. If the script was invoked directly, the APAGE macro is also
  11819. executed. Otherwise, it is available for subsequent and perhaps
  11820. repeated use later in the Kermit session.
  11821. An especially handy use for Kerbang scripts is to have the
  11822. initialization file itself be one. Since the standard initialization
  11823. file is rather long and time-consuming to execute, it is often overkill
  11824. if you want to start Kermit just to transfer a file. Of course there
  11825. are command-line switches to suppress initialization-file execution,
  11826. etc, but another approach is to "run" the initialization file when you
  11827. want its features (notably the services directory), and run C-Kermit
  11828. directly when you don't. A setup like this requires that (a) the
  11829. C-Kermit initialization file is configured as a Kerbang script (has
  11830. #!/path.../kermit as first line), has execute permission, and is in
  11831. your PATH; and (b) that you don't have a .kermrc file in your login
  11832. directory.
  11833. 7.20. IF and XIF Statement Syntax
  11834. The IF command has been improved in two significant ways in C-Kermit
  11835. 7.0, described in the following subsections. All changes are backwards
  11836. compatible.
  11837. 7.20.1. The IF/XIF Distinction
  11838. The distinction between IF and XIF is no longer important as of
  11839. C-Kermit 7.0. You should be able to use IF in all cases (and of course,
  11840. also XIF for backwards compatibility). In the past, IF was used for
  11841. single-command THEN parts, followed optionally by a separate ELSE
  11842. command:
  11843. IF condition command1 ; THEN part
  11844. ELSE command2 ; ELSE part
  11845. whereas XIF was required if either part had multiple commands:
  11846. XIF condition { command, command, ... } ELSE { command, command, ... }
  11847. The syntactic differences were primarily that IF / ELSE was two
  11848. commands on two separate lines, whereas XIF was one command on one
  11849. line, and that XIF allowed (and in fact required) braces around its
  11850. command lists, whereas IF did not allow them.
  11851. Furthermore, the chaining or nesting of parts and conditions was
  11852. inconsistent. For example, the IF command could be used like this:
  11853. IF condition command
  11854. ELSE IF condition command
  11855. ELSE IF condition command
  11856. ELSE IF condition command
  11857. ...
  11858. but XIF could not. C-Kermit 7.0 accepts the old syntax and executes it
  11859. the same as previous versions, but also accepts a new unified and more
  11860. convenient syntax:
  11861. IF condition command-list [ ELSE command-list ]
  11862. or:
  11863. IF condition command-list
  11864. ELSE command-list
  11865. in which the ELSE part is optional, and where command-list can be a
  11866. single command (with or without braces around it) or a list of commands
  11867. enclosed in braces. Examples:
  11868. Example 1:
  11869. IF condition { command1, command2 } ELSE { command3, command4 }
  11870. Example 2 (same as Example 1):
  11871. IF condition {
  11872. command1
  11873. command2
  11874. } ELSE {
  11875. command3
  11876. command4
  11877. }
  11878. Example 3 (same as 1 and 2):
  11879. IF condition {
  11880. command1
  11881. command2
  11882. }
  11883. ELSE { command3, command4 }
  11884. Example 4 (same as 1-3):
  11885. IF condition {
  11886. command1
  11887. command2
  11888. }
  11889. ELSE {
  11890. command3
  11891. command4
  11892. }
  11893. Example 5 (ELSE can be followed by another command):
  11894. IF condition1 {
  11895. command1
  11896. command2
  11897. } ELSE IF condition2 {
  11898. command3
  11899. command4
  11900. } ELSE {
  11901. command5
  11902. command6
  11903. }
  11904. Example 5 suggests other possibilities:
  11905. IF condition {
  11906. command1
  11907. command2
  11908. } ELSE FOR variable initial final increment {
  11909. command3
  11910. command4
  11911. }
  11912. And this too is possible, except for some non-obvious quoting
  11913. considerations:
  11914. dcl \&a[6] = one two three four five six
  11915. IF < \%n 3 {
  11916. echo \\%n is too small: \%n
  11917. } ELSE FOR \\%i 1 \\%n 1 {
  11918. echo \\%i. \\&a[\\%i]
  11919. }
  11920. (The loop variable must be quoted in this context to prevent premature
  11921. evaluation.)
  11922. Many C programmers prefer to code IF-ELSE, WHILE, FOR, and SWITCH with
  11923. the block-open bracket on its own line. This does not work in Kermit:
  11924. IF condition ; THIS FORMAT DOES NOT NOT WORK
  11925. {
  11926. command1
  11927. command2
  11928. }
  11929. ELSE
  11930. {
  11931. command3
  11932. command4
  11933. }
  11934. Explanation: the Kermit command language is line oriented; each line is
  11935. a command, each command is a line. The first line above, having no hint
  11936. of continuation, is an incomplete command, yet syntactically correct --
  11937. an IF statement with an empty THEN part. Interestingly enough, since
  11938. the next line begins with "{" it is a block that (inC-Kermit 8.0
  11939. and later) is a block that is executed unconditionally. Thus the
  11940. commands in the THEN part are executed regardless of whether the
  11941. condition is true -- not what you wanted!
  11942. The new block syntax used in the IF, WHILE, FOR, and SWITCH commands
  11943. employs certain tricks to allow multiple lines to be treated as a
  11944. single line:
  11945. * Any line ending with "{" (ignoring whitespace and comments) marks
  11946. the beginning of a block;
  11947. * Any line beginning with "}" (ignoring whitespace) marks the end of
  11948. a block;
  11949. * Line breaks within a block separate commands; the comma is implied
  11950. by the line end.
  11951. Thus:
  11952. IF condition {
  11953. command1
  11954. command2
  11955. } ELSE {
  11956. command3
  11957. command4
  11958. }
  11959. is "assembled" into:
  11960. IF condition { command1, command2 } ELSE { command3, command4 }
  11961. Note the addition of commas to separate commands within blocks. As
  11962. always, if you need continue a command onto additional lines, you can
  11963. end the continued lines with the continuation character, "-". You can
  11964. also do this if you want to put opening brackets on their own line:
  11965. IF condition -
  11966. {
  11967. command1
  11968. command2
  11969. }
  11970. ELSE -
  11971. {
  11972. command3
  11973. command4
  11974. }
  11975. 7.20.2. Boolean Expressions (The IF/WHILE Condition)
  11976. Prior to C-Kermit 7.0, the IF and WHILE commands accepted only a single
  11977. Boolean ("true or false") assertion, e.g. "if > \%m 0 command" or "if
  11978. exist filename command". There was no way to form Boolean expressions
  11979. and, in particular, nothing that approached a Boolean OR function (AND
  11980. could be simulated by concatenating IF statements: "if condition1 if
  11981. condition2..").
  11982. C-Kermit 7.0 (and K95 1.1.19) allow grouping of Boolean assertions
  11983. using parentheses and combining them using AND (or &&) and OR (or ||).
  11984. Each of these operators -- including the parentheses -- is a field and
  11985. must be set off by spaces. AND has higher precedence than OR, NOT has
  11986. higher precedence than AND, but parentheses can be used to force any
  11987. desired order of evaluation. The old syntax is still accepted.
  11988. Here are some examples:
  11989. define \%z 0 ; Define some variables
  11990. define \%n 1 ; for use in the examples.
  11991. if > \%n \%z echo \%n is greater. ; Original format - still accepted.
  11992. if ( > \%n \%z ) echo \%n is greater. ; Parentheses may be used in 7.0.
  11993. if ( > \%n \%z && not = \%z 0 ) ... ; Two assertions combined with AND.
  11994. if ( > \%n \%z and not = \%z 0 ) ... ; Same as previous ("and" = "&&").
  11995. if ( > \%n \%z || not = \%z 0 ) ... ; Two assertions combined with OR.
  11996. if ( > \%n \%z or not = \%z 0 ) ... ; Same as previous ("or" = "||").
  11997. if ( > \%n \%z || != \%z 0 ) ... ; Ditto ("!=" = "not =").
  11998. while ( 1 ) { ... } ; Just like C.
  11999. Notice the spaces around all operators including the parentheses --
  12000. these are required. The following examples show how parentheses can be
  12001. used to alter the precedence of the AND and OR operators:
  12002. if ( false || false && false || true ) ,.. ; True
  12003. if ( false || ( false && false ) || true ) ... ; Same as previous
  12004. if ( ( false || false ) && ( false || true ) ) ... ; False
  12005. Similarly for NOT:
  12006. if ( not true && false ) ... ; False (NOT binds to TRUE only)
  12007. if ( ( not true ) && false ) ... ; Same as previous
  12008. if ( not ( true && false ) ) ... ; True (NOT binds to (TRUE && FALSE))
  12009. Notes:
  12010. 1. The syntax of the Boolean expression itself has not changed; each
  12011. expression begins with a keyword or token such as "EXIST", ">", or
  12012. "=", etc; operators such as "<", "=", and ">" do not go between
  12013. their operands but precede them as before; this might be called
  12014. "reverse reverse Polish notation"; it allows deterministic
  12015. on-the-fly parsing of these expressions at the C-Kermit> prompt as
  12016. well as in scripts, and allows ?-help to be given for each item
  12017. when IF or WHILE commands are typed at the prompt.
  12018. 2. Parentheses are required when there is more than one Boolean
  12019. assertion.
  12020. 3. Parentheses are not required, but are allowed, when there is only
  12021. one Boolean assertion.
  12022. 4. Evaluation of Boolean assertions occurs left to right, but the
  12023. resulting Boolean expression is evaluated afterwards according to
  12024. the rules of precedence. All Boolean assertions are always
  12025. evaluated; there is no "early stopping" property and therefore no
  12026. question about when or if side effects will occur -- if any Boolean
  12027. assertion has side effects, they will always occur. (Early stopping
  12028. is, however, possible with theS-Expression IF introduced in
  12029. C-Kermit 8.0.)
  12030. Constructions of arbitrary complexity are possible, within reason.
  12031. Also see Section 7.4 for new IF / WHILE conditions.
  12032. 7.21. Screen Formatting and Cursor Control
  12033. C-Kermit 7.0 adds a simple way to create formatted screens, the SCREEN
  12034. command:
  12035. SCREEN { CLEAR, CLEOL, MOVE-TO row [ column ] }
  12036. Performs screen-formatting actions. Correct operation of these
  12037. commands depends on proper terminal setup on both ends of the
  12038. connection -- mainly that the host terminal type is set to agree
  12039. with the kind of terminal or the emulation you are viewing
  12040. C-Kermit through. The UNIX version uses terminfo or termcap (not
  12041. curses); the VMS version uses SMG; K-95 uses its built in screen
  12042. manager.
  12043. SCREEN CLEAR
  12044. Moves the cursor to home position and clears the entire screen.
  12045. Synonyms: CLEAR COMMAND-SCREEN ALL (K-95 only), CLS, CLEAR
  12046. SCREEN.
  12047. SCREEN CLEOL
  12048. Clears from the current cursor position to the end of the line.
  12049. Synonym: CLEAR COMMAND-SCREEN EOL (K-95 only)
  12050. SCREEN MOVE-TO row column
  12051. Moves the cursor to the indicated row and column. The row and
  12052. column numbers are 1-based, so on a 24x80 screen the home
  12053. position is 1 1 and the lower right corner is 24 80. If a row or
  12054. column number is given that too large for what Kermit or the
  12055. operating system thinks is your screen size, the appropriate
  12056. number is substituted.
  12057. These escape sequences used by these commands depends on the platform.
  12058. In UNIX, your TERM environment variable is used to query the
  12059. terminfo/termcap database; if the query fails, ANSI/VT100 sequences are
  12060. used. In VMS, the SMG library is used, which sends sequences based on
  12061. your VMS terminal type. K95 does its own screen control. On other
  12062. platforms (such as AOS/VS, VOS, etc), screen formatting is not
  12063. supported, and the SCREEN command does nothing.
  12064. The three SCREEN actions can be used in scripts to produce menus,
  12065. formatted screens, dynamic displays, etc. Related variables include:
  12066. \v(terminal) The type terminal C-Kermit thinks you have.
  12067. \v(rows) The number of rows C-Kermit thinks your terminal has.
  12068. \v(columns) The number of columns C-Kermit thinks your terminal has.
  12069. And functions:
  12070. \fscrncurx() The current X coordinate of the cursor (K-95 only).
  12071. \fscrncury() The current Y coordinate of the cursor (K-95 only).
  12072. \fscrnstr(x,y,n) The string of length nat position (x,y) (K-95 only).
  12073. And commands:
  12074. ECHO string Writes string + CRLF at the current cursor position.
  12075. XECHO string Writes string at current cursor position; CRLF not supplied.
  12076. GETC v prompt Issues prompt, reads one character into variable v, no echo.
  12077. And special characters:
  12078. Ctrl-L At the C-Kermit> command prompt, or in a C-Kermit command,
  12079. works like Return or Enter, but also clears the screen
  12080. Example 1: A macro that prints a message \%1 at cursor position
  12081. (\%2,\%3):
  12082. define MSG {
  12083. if not def \%3 def \%3 0 ; Default column to 0
  12084. if > \v(argc) 2 screen move \%2 \%3 ; Move to given row/col (if any)
  12085. screen cleol ; Clear to end of line
  12086. if def \%1 xecho \fcontents(\%1) ; Print message (if any)
  12087. }
  12088. Example 2: A macro put the cursor on the bottom screen line, left
  12089. margin:
  12090. define BOT {
  12091. screen move \v(rows) 0
  12092. }
  12093. Example 3: A macro to center message \%1 on line \%2.
  12094. define CENTER {
  12095. if not def \%2 def \%2 1
  12096. .\%x ::= (\v(cols)-\flen(\%1))/2
  12097. msg {\%1} {\%2} {\%x}
  12098. }
  12099. Example 4: A simple menu (building on Examples 1-3):
  12100. def \%c 0 ; Menu choice variable
  12101. screen clear ; Clear the screen
  12102. center {Welcome to This Menu} 2 ; Display the menu
  12103. msg {Choices:} 4
  12104. msg { 1. File} 6
  12105. msg { 2. Edit} 7
  12106. msg { 3. Exit} 8
  12107. while ( != \%c 3 ) { ; Read and verify choice
  12108. while true { ; Keep trying till we get a good one
  12109. screen move 10 ; Move to line 10
  12110. screen cleol ; Clear this line
  12111. getc \%c {Your choice: } ; Prompt and get and echo 1 character
  12112. xecho \%c
  12113. if ( not numeric \%c ) { msg {Not numeric - "\%c"} 12, continue }
  12114. if ( >= \%c 1 && <= \%c 3 ) break
  12115. msg {Out of range - "\%c"} 12
  12116. }
  12117. switch \%c { ; Valid choice - execute it.
  12118. :1, msg {Filing... } 12, break
  12119. :2, msg {Editing...} 12, break
  12120. :3, msg {Exiting...} 12, break
  12121. }
  12122. }
  12123. echo Bye ; Exit chosen - say goodbye.
  12124. bot ; Leave cursor at screen bottom.
  12125. exit ; And exit.
  12126. Similar scripts can work over the communication connection; substitute
  12127. INPUT and OUTPUT for GETC and ECHO/XECHO.
  12128. 7.22. Evaluating Arithmetic Expressions
  12129. A new arithmetic operator was added to the list recognized by the
  12130. EVALUATE command, the \feval() function, and which can also be used
  12131. anywhere else arithmetic expressions are accepted (numeric command
  12132. fields, array subscripts, etc):
  12133. Prefix "!"
  12134. This operator inverts the "truth value" of the number or
  12135. arithmetic expression that follows. If the value of the operand
  12136. is 0, the result is 1. If the value is nonzero, the result is 0.
  12137. Examples:
  12138. set eval old
  12139. evaluate 0
  12140. 0
  12141. evaluate !0
  12142. 1
  12143. evaluate !3
  12144. 0
  12145. evaluate !(-3)
  12146. 0
  12147. .\%a = 1
  12148. .\%b = 0
  12149. evaluate !(\%a|\%b)
  12150. 0
  12151. evaluate !(\%a&\%b)
  12152. 1
  12153. evaluate !(!(\%a&\%b))
  12154. 0
  12155. Note the distinction between Prefix ! (invert truth value) and Suffix !
  12156. (factorial). Also the distinction between Prefix ! and Prefix ~ (which
  12157. inverts all the bits in its operand). Also note that prefix operators
  12158. (!, -, and ~) can not be adjacent unless you use parentheses to
  12159. separate them, as shown in the final example above.
  12160. 7.23. Floating-Point Arithmetic
  12161. For a more convenient way of dealing with floating-point numbers
  12162. than the one described here, see theC-Kermit 8.0 update notes,
  12163. the section onS-Expressions.
  12164. C-Kermit 7.0 adds limited support for floating-point numbers (numbers
  12165. that have fractional parts, like 3.141592653). This support is provided
  12166. through a small repertoire of functions and in Boolean expressions that
  12167. compare numbers, but does not apply to number parsing in general, or to
  12168. expression evaluation, array subscripts, the INCREMENT and DECREMENT
  12169. commands, or in any context other than those listed in this section.
  12170. A floating point number has an optional sign (+ or -), followed by a
  12171. series of decimal digits containing either zero or one period (.)
  12172. character, which is the decimal point. The use of comma or any other
  12173. character besides period as a decimal point is not supported.
  12174. Scientific notation is not supported either. Examples of legal
  12175. floating-point numbers:
  12176. 0 Integers can be used
  12177. 1 Ditto
  12178. 2. A decimal point without decimal digits
  12179. 3.0 A decimal point with decimal digits
  12180. 3.141592653 Ditto
  12181. -4.0 A negative sign can be included
  12182. +5.0 A positive sign can be included
  12183. Examples of notations that are not accepted:
  12184. 1,000,000 Separators can not be used
  12185. 1.000.000 Ditto (or multiple decimal points)
  12186. 6.022137E23 No scientific notation
  12187. 6.62606868e-34 Ditto
  12188. 12.5+6.25 No "bare" expressions
  12189. You can use IF FLOAT test a string or variable to see if it's in
  12190. acceptable floating-point format. Example:
  12191. ask \%f { Type a number: }
  12192. if not def \%f .\%f = 0.0
  12193. if not float \%f stop 1 Invalid floating-point number: "\%f"
  12194. C-Kermit's floating-point support, like its support for whole numbers
  12195. (integers), relies on the capabilities of the underlying computer. Your
  12196. computer has only a limited amount of precision for numbers, depending
  12197. on its architecture. Thus floating-point numbers that have too many
  12198. digits will not be accurate; adding a very small number to a very large
  12199. one might have no effect at all; and so on. For details, read a text on
  12200. numerical analysis. Example:
  12201. .\%a = 11111111111111111111 ; A long number
  12202. .\%b = 22222222222222222222 ; Another one
  12203. echo \ffpadd(\%a,\%b) ; Add them - the result should be all 3's
  12204. 33333333333333330000.0 ; See the result
  12205. In this example, the computer has 16 digits of precision; after that,
  12206. the (low-order) digits are set to 0, since the computer doesn't know
  12207. what they really are. In fact, the computer returns random digits, but
  12208. Kermit sets all digits beyond the computer's precision to 0.
  12209. C-Kermit's floating-point functions have names of the form
  12210. "\ffpxxx(args)" ("\f" for function, "fp" for floating-point), where
  12211. "xxx" is replaced by the name of the function, such as "sqrt", and
  12212. "args" is the argument list, consisting of one or two floating-point
  12213. numbers (depending on the function), and an optional "d" argument that
  12214. says now many decimal places should be shown in the result. Example:
  12215. \ffpdiv(10,3,1) returns "3.3"
  12216. \ffpdiv(10,3,2) returns "3.33"
  12217. \ffpdiv(10,3,3) returns "3.333"
  12218. and so on, up to the precision of the computer. If the decimal-places
  12219. argument is less than zero, the fractional part of the result is
  12220. truncated:
  12221. \ffpdiv(10,3,-1) returns "3".
  12222. If the decimal-places argument is 0, or is omitted, C-Kermit returns as
  12223. many decimal places as are meaningful in the computer's floating-point
  12224. precision, truncating any extraneous trailing 0's:
  12225. \ffpdiv(10,8) returns "1.25".
  12226. \ffpdiv(10,4) returns "2.5".
  12227. \ffpdiv(10,2) returns "5.0".
  12228. \ffpdiv(10,3) returns "3.333333333333333" (for 16-digit precision).
  12229. There is no way to request that a floating-point function return a
  12230. decimal point but no decimal places. However, this is easy enough to
  12231. accomplish in other ways, for example by supplying it outside the
  12232. function call:
  12233. echo \ffpadd(\%a,\%b,-1).
  12234. Kermit's floating-point functions always round the result for the
  12235. requested number of decimal places when the "d" argument is given and
  12236. has a value greater than 0 (see the description of \ffpround() just
  12237. below).
  12238. Floating-point arguments can be constants in floating-point format or
  12239. variables whose values are floating-point numbers. If a floating-point
  12240. argument is omitted, or is a variable with no value, 0.0 is supplied
  12241. automatically. Example:
  12242. def \%x 999.999
  12243. undef \%y
  12244. echo \ffpmin(\%x,\%y)
  12245. 0.0
  12246. Or equivalently:
  12247. echo \ffpmin(999.999)
  12248. 0.0
  12249. The floating-point functions are:
  12250. \ffpround(f1,d)
  12251. Returns f1 rounded to d decimal places. For this function only,
  12252. d = 0 (or d omitted) has a special meaning: return the integer
  12253. part of f1 rounded according to the fractional part. Examples:
  12254. \ffpround(2.74653,-1) returns "2" (fraction truncated, no rounding).
  12255. \ffpround(2.74653,0) returns "3" (integer part is rounded).
  12256. \ffpround(2.74653) returns "3" (d omitted same as d = 0).
  12257. \ffpround(2.74653,1) returns "2.7".
  12258. \ffpround(2.74653,2) returns "2.75".
  12259. \ffpround(2.74653,3) returns "2.747".
  12260. \ffpround(2.74653,4) returns "2.7465", etc.
  12261. \ffpadd(f1,f2,d)
  12262. Returns the sum of f1 and f2.
  12263. \ffpsubtract(f1,f2,d)
  12264. Subtracts f2 from f1 and returns the result.
  12265. \ffpmultiply(f1,f2,d)
  12266. Returns the product of f1 and f2.
  12267. \ffpdivide(f1,f2,d)
  12268. If f2 is not 0, divides f1 by f2 and returns the quotient.
  12269. If f2 is 0, a DIVIDE_BY_ZERO error occurs.
  12270. \ffpraise(f1,f2,d)
  12271. If f1 = 0 and f2 <= 0, or if f1 < 0 and f2 has a fractional
  12272. part, an ARG_OUT_OF_RANGE error occurs; otherwise f1 raised to
  12273. the f2 power is returned.
  12274. \ffpsqrt(f1,d)
  12275. If f1 >= 0, returns the square root of f1; otherwise
  12276. ARG_OUT_OF_RANGE.
  12277. \ffpabsolute(f1,d)
  12278. Returns the absolute value of f1 (i.e. f1 without a sign). This
  12279. is the floating-point analog of \fabsolute(n1).
  12280. \ffpint(f1)
  12281. Returns the integer part of f1. Equivalent to \ffpround(f1,-1).
  12282. \ffpexp(f1,d)
  12283. The base of natural logarithms, e (2.718282...), raised to the
  12284. f1 power.
  12285. \ffplogn(f1,d)
  12286. The natural logarithm of f1 (the power to which e must be raised
  12287. to obtain f1).
  12288. \ffplog10(f1,d)
  12289. The base-10 logarithm of f1 (the power to which 10 must be
  12290. raised to obtain f1).
  12291. \ffpmodulus(f1,f2,d)
  12292. If f2 is not 0, the remainder after dividing f1 by f2.
  12293. If f2 is 0, a DIVIDE_BY_ZERO error occurs.
  12294. This is the floating-point analog of \fmod(n1,n2).
  12295. \ffpmaximum(f1,f2,d)
  12296. Returns the maximum of f1 and f2. This is the floating-point
  12297. analog of \fmax(n1,n2).
  12298. \ffpminimum(f1,f2,d)
  12299. Returns the minimum of f1 and f2. This is the floating-point
  12300. analog of \fmin(n1,n2).
  12301. \ffpsine(f1,d)
  12302. Returns the sine of f1 radians.
  12303. \ffpcosine(f1,d)
  12304. Returns the cosine of f1 radians.
  12305. \ffptangent(f1,d)
  12306. Returns the tangent of f1 radians.
  12307. Note that all of these functions can be used with integer arguments. If
  12308. you want an integer result, specify d = -1 (to truncate) or feed the
  12309. result to \ffpround(xxx,0) (to round).
  12310. Floating-point numbers (or variables or functions that return them) can
  12311. be used in Boolean expressions (see Section 7.20.2) that compare
  12312. numbers:
  12313. = x y
  12314. != x y
  12315. < x y
  12316. > x y
  12317. <= x y
  12318. >= x y
  12319. In these examples, x and y can be either integers or floating-point
  12320. numbers in any combination. In an arithmetic comparison of an integer
  12321. and a floating-point number, the integer is converted to floating-point
  12322. before the comparison is made. Examples:
  12323. .\%t = 3.000000000
  12324. .\%f = 3.141592653
  12325. .\%i = 3
  12326. if > \%f \%i echo Pi is greater.
  12327. if = \%t \%i echo "\%i" = "\%t".
  12328. A floating-point number can also be used in:
  12329. IF number command
  12330. where the command is executed if the number is nonzero. If the number
  12331. is floating-point, the command is not executed if the number is 0.0,
  12332. and is executed otherwise.
  12333. Floating-point numbers can be sorted using ARRAY SORT /NUMERIC (see
  12334. Section 7.10.5 ).
  12335. Two floating-point constants are provided:
  12336. \v(math_pi) = Pi (3.141592653...)
  12337. \v(math_e) = e, the base of natural logarithms (2.71828...)
  12338. These are given to the computer's precision, e.g. 16 digits. This
  12339. number itself is available in a variable:
  12340. \v(math_precision)
  12341. How many significant digits in a floating-point number.
  12342. 7.24. Tracing Script Execution
  12343. The TRACE command is handy for debugging scripts.
  12344. TRACE [ { /ON, /OFF } ] [ { ASSIGNMENTS, COMMAND-LEVEL, ALL } ]
  12345. Selects tracing of the given object.
  12346. Optional switches are /ON and /OFF. If no switch is given, /ON is
  12347. implied. The trace objects are ASSIGNMENTS, COMMAND-LEVEL, and ALL. The
  12348. default object is ALL, meaning to select all trace objects (besides
  12349. ALL). Thus TRACE by itself selects tracing of everything, as does TRACE
  12350. /ON, and TRACE /OFF turns off all tracing.
  12351. When tracing of ASSIGNMENTS is on, every time the value of any
  12352. user-defined variable or macro changes, C-Kermit prints one of the
  12353. following:
  12354. >>> name: "value"
  12355. The name of the variable or macro followed by the new value in
  12356. quotes. This includes implicit macro-parameter assignments
  12357. during macro invocation.
  12358. >>> name: (undef)
  12359. This indicates that the variable or macro has been undefined.
  12360. <<< name: "value"
  12361. For RETURN statements: the name of the macro and the return
  12362. value.
  12363. <<< name: (null)
  12364. For RETURN statements that include no value or an empty value.
  12365. When tracing of COMMAND-LEVEL is on, C-Kermit prints:
  12366. [n] +F: "name"
  12367. Whenever a command file is entered, where "n" is the command
  12368. level (0 = top); the name of the command file is shown in
  12369. quotes.
  12370. [n] +M: "name"
  12371. Whenever a macro is entered; "n" is the command level. The name
  12372. of the macro is shown in quotes.
  12373. [n] -F: "name"
  12374. Whenever a command file is reentered from below, when a macro or
  12375. command file that it has invoked has returned.
  12376. [n] -M: "name"
  12377. Whenever a macro is reentered from below.
  12378. For other debugging tools, see SHOW ARGS, SHOW STACK, SET TAKE, SET
  12379. MACRO, and of course, ECHO.
  12380. 7.25. Compact Substring Notation
  12381. It is often desirable to extract a substring from a string which is
  12382. stored in a variable, and for this we have the \fsubstring() function,
  12383. which is used like this:
  12384. define \%a 1234567890
  12385. echo \fsubstring(\%a,3,4) ; substring from 3rd character length 4
  12386. 3456
  12387. or like this with macro-named variables:
  12388. define string 1234567890
  12389. echo \fsubstring(\m(string),3,4)
  12390. 3456
  12391. C-Kermit 7.0 adds a pair of alternative compact notations:
  12392. \:(variablename[start:length]) <-- Substring of variable's value
  12393. \s(macroname[start:length]) <-- Substring of macro's definition
  12394. These are exactly equivalent to using \fsubstring(), except more
  12395. compact to write and also faster since evaluation is in one step
  12396. instead of two.
  12397. The "\:()" notation can be used with any Kermit variable, that is,
  12398. almost anything that starts with a backslash:
  12399. \:(\%a[2:6]) <-- equivalent to \fsubstring(\%a,2,6)
  12400. \:(\&x[1][2:6]) <-- equivalent to \fsubstring(\&x[1],2,6)
  12401. \:(\m(foo)[2:6]) <-- equivalent to \fsubstring(\m(foo),2,6)
  12402. \:(\v(time)[2:6]) <-- equivalent to \fsubstring(\v(time),2,6)
  12403. \:(\$(TERM)[2:6]) <-- equivalent to \fsubstring(\$(TERM),2,6)
  12404. \:(ABCDEFGH[2:6]) <-- equivalent to \fsubstring(ABCDEFGH,2,6)
  12405. Whatever appears between the left parenthesis and the left bracket is
  12406. evaluated and then the indicated substring of the result is returned.
  12407. The "\s()" notation is the same, except after evaluating the variable,
  12408. the result is treated as a macro name and is looked up in the macro
  12409. table. Then the indicated substring of the macro definition is
  12410. returned. Example:
  12411. define testing abcdefghijklmnopqrstuvwxyz
  12412. define \%a testing
  12413. \s(testing[2:6]) --> bcdefg
  12414. \:(testing[2:6]) --> esting
  12415. \:(\%a[2:6]) --> esting
  12416. \s(\%a[2:6]) --> bcdefg
  12417. Note that the following two examples are equivalent:
  12418. \:(\m(foo)[2:6])
  12419. \s(foo[2:6])
  12420. The first number in the brackets is the 1-based starting position. If
  12421. it is omitted, or less than 1, it is treated as 1. If it is greater
  12422. than the length of the string, an empty string is returned.
  12423. The second number is the length of the desired substring. If the second
  12424. number is omitted, is less than 0, or would be past the end of the
  12425. string, then "through the end of the string" is assumed. If it is 0,
  12426. the empty string is returned.
  12427. If the brackets are empty or omitted, the original string is returned.
  12428. The starting position and length need not be literal numbers; they can
  12429. also be variables, functions, arithmetic expressions, or even other
  12430. \s() or \:() quantities; anything that evaluates to a number, for
  12431. example:
  12432. \s(block[1025:\fhex2n(\s(block[\%b:\%n+4]))/2])
  12433. Syntactically, \m(name) and \s(name) differ only in that the sequence
  12434. [*] at the end of the name (where * is any sequence of 0 or more
  12435. characters) is treated as substring notation in \s(name), but is
  12436. considered part of the name in \m(name) (to see why, seeSection
  12437. 7.10.9).
  12438. 7.26. New WAIT Command Options
  12439. The WAIT command has been extended to allow waiting for different kinds
  12440. of things (formerly it only waited for modem signals). Now it also can
  12441. wait for file events.
  12442. 7.26.1. Waiting for Modem Signals
  12443. The previous syntax:
  12444. WAIT time { CD, DSR, RTS, RI, ... }
  12445. has changed to:
  12446. WAIT time MODEM-SIGNALS { CD, DSR, RTS, RI, ... }
  12447. However, the previous syntax is still accepted. The behavior is the
  12448. same in either case.
  12449. 7.26.2. Waiting for File Events
  12450. The new WAIT option:
  12451. WAIT time FILE { CREATION, DELETION, MODIFICATION } filename
  12452. lets you tell Kermit to wait the given amount of time (or until the
  12453. given time of day) for a file whose name is filename to be created,
  12454. deleted, or modified, respectively. The filename may not contain
  12455. wildcards. If the specified event does not occur within the time limit,
  12456. or if WAIT CANCELLATION is ON and you interrupt from the keyboard
  12457. before the time is up, the WAIT command fails. If the event is
  12458. MODIFICATION and the file does not exist, the command fails. Otherwise,
  12459. if the given event occurs within the time limit, the command succeeds.
  12460. Examples:
  12461. WAIT 600 FILE DELETION oofa.tmp
  12462. Wait up to 10 minutes for file oofa.tmp to disappear.
  12463. WAIT 23:59:59 FILE MOD orders.db
  12464. Wait until just before midnight for the orders.db file to be
  12465. changed.
  12466. Example: Suppose you want to have the current copy of /etc/motd on your
  12467. screen at all times, and you want to hear a bell whenever it changes:
  12468. def \%f /etc/motd ; The file of interest.
  12469. while 1 { ; Loop forever...
  12470. cls ; Clear the screen.
  12471. echo \%f: \v(date) \v(time)... ; Print 2-line heading...
  12472. echo
  12473. if ( not exist \%f ) { ; If file doesn't exist,
  12474. echo \%f does not exist... ; print message,
  12475. wait 600 file creat \%f ; and wait for it to appear.
  12476. continue
  12477. }
  12478. beep ; Something new - beep.
  12479. type /head:\v(rows-2) \%f ; Display the file
  12480. if fail exit 1 \%f: \ferrstring() ; (checking for errors).
  12481. wait 999 file mod \%f ; Wait for it to change.
  12482. }
  12483. This notices when the file is created, deleted, or modified, and acts
  12484. only then (or when you interrupt it with); the time shown in the
  12485. heading is the time of the most recent event (including when the
  12486. program started).
  12487. See Section 1.10, where the \v(kbchar) variable is explained. This
  12488. lets you modify a loop like the one above to also accept
  12489. single-character commands, which interrupt the WAIT, and dispatch
  12490. accordingly. For example:
  12491. wait 999 file mod \%f ; Wait for the file to change.
  12492. if defined \v(kbchar) { ; Interrupted from keyboard?
  12493. switch \v(kbchar) { ; Handle the keystroke...
  12494. :q, exit ; Q to Quit
  12495. :h, echo blah blah, break ; H for Help
  12496. :default, beep, continue ; Anything else beep and ignore
  12497. }
  12498. }
  12499. This lets you write event-driven applications that wait for up to three
  12500. events at once: a file or modem event, a timeout, and a keystroke.
  12501. 7.27. Relaxed FOR and SWITCH Syntax
  12502. For consistency with the extended IF and WHILE syntax, the FOR and
  12503. SWITCH control lists may (but need not be) enclosed in parentheses:
  12504. FOR ( \%i 1 \%n 1 ) { command-list... }
  12505. SWITCH ( \%c ) { command-list... }
  12506. In the FOR command, the increment item can be omitted if the control
  12507. list is enclosed in parentheses, in which case the increment defaults
  12508. appropriately to 1 or -1, depending on the values of the first two
  12509. variables.
  12510. As with IF, the parentheses around the FOR-command control list must be
  12511. set off by spaces (in the SWITCH command, the spaces are not required
  12512. since the SWITCH expression is a single arithmetic expression).
  12513. Also, outer braces around the command list are supplied automatically
  12514. if you omit them, e.g.:
  12515. FOR ( \%i 1 %n 1 ) echo \%i
  12516. 8. USING OTHER FILE TRANSFER PROTOCOLS
  12517. In C-Kermit 7.0, alternative protocols can be selected using switches.
  12518. Switches are described in Section 1.5; the use of
  12519. protocol-selection switches is described in Section 4.7.1.
  12520. Example:
  12521. send /binary /protocol:zmodem x.tar.gz
  12522. Note that file transfer recovery works only with Kermit and Zmodem
  12523. protocols. With Zmodem, recovery can be initiated only by the sender.
  12524. Only pre-1988 versions of the publicly-distributed sz/rz programs use
  12525. Standard I/O; those released later than that do not use Standard I/O
  12526. and therefore do not work with REDIRECT. However, Omen Technology does
  12527. offer an up-to-date redirectable version called crzsz, which must be
  12528. licensed for use:
  12529. "Unix Crz and Csz support XMODEM, YMODEM, and ZMODEM transfers when
  12530. called by dial-out programs such as Kermit and certain versions of
  12531. cu(1). They are clients designed for this use.
  12532. "Crz and Csz are Copyrighted shareware programs. Use of these
  12533. programs beyond a brief evaluation period requires registration.
  12534. Please print the "mailer.rz" file, fill out the form and return same
  12535. with your registration."
  12536. To use the crzsz programs as your external XYZMODEM programs in
  12537. C-Kermit, follow the instructions in the book, but put a "c" before
  12538. each command, e.g.:
  12539. set protocol zmodem {csz %s} {csz -a %s} crz crz crz crz
  12540. To use Zmodem protocol over Telnet or other non-transparent
  12541. connections, you might need to add the -e (Escape) option:
  12542. set protocol zmodem {csz -e %s} {csz -e -a %s} crz crz crz crz
  12543. 9. COMMAND-LINE OPTIONS
  12544. 9.0. Extended-Format Command-Line Options
  12545. Standard UNIX command line options are a single letter. C-Kermit has
  12546. run out of letters, so new options are in a new extended format:
  12547. --word[:arg]
  12548. where a keyword (rather than a single letter) specifies the function,
  12549. and if an argument is to be included, it is separated by a colon (or
  12550. equal sign). Most of the new extended-format command-line options are
  12551. only for use with the Internet Kermit Service Daemon; see theIKSD
  12552. Administration Guide for details. However, several of them are also
  12553. general in nature:
  12554. --nointerrupts
  12555. Disables keyboard interrupts that are normally enabled, which
  12556. are usually Ctrl-C (to interrupt a command) and Ctrl-Z (UNIX
  12557. only, to suspend C-Kermit).
  12558. --help
  12559. Lists the extended command-line options that are available in
  12560. your version of C-Kermit. If any options seem to be missing,
  12561. that is because your copy of C-Kermit was built with
  12562. compile-time options to deselect them.
  12563. --helpfile:filename
  12564. Specifies the name of a file to be displayed if the user types
  12565. HELP (not followed by a specific command or topic), in place of
  12566. the built-in top-level help text. The file need not fit on one
  12567. screen; more-prompting is used if the file is more than one
  12568. screen long if COMMAND MORE-PROMPTING is ON, as it is by
  12569. default.
  12570. --bannerfile:filename
  12571. The name of a file containing a message to be printed after the
  12572. user logs in, in place of the normal message (Copyright notice,
  12573. "Type HELP or ? for help", "Default transfer mode is...", etc).
  12574. --cdmessage:{on,off,0,1,2}
  12575. For use in the Server-Side Server configuration; whenever the
  12576. client tells the server to change directory, the server sends
  12577. the contents of a "read me" file to the client's screen. This
  12578. feature is On by default, and operates only in client/server
  12579. mode when ON or 1. If set to 2 or higher, it also operates when
  12580. the CD command is given at the IKSD> prompt. Synonym: --cdmsg.
  12581. --cdfile:filename
  12582. When cdmessage is on, this is the name of the "read me" file to
  12583. be sent. Normally you would specify a relative (not absolute)
  12584. name, since the file is opened using the literal name you
  12585. specified, after changing to the new directory. Example:
  12586. --cdfile:READ.ME
  12587. You can also give a list of up to 8 filenames by (a) enclosing
  12588. each filename in braces, and (b) enclosing the entire list in
  12589. braces. Example:
  12590. --cdfile:{{./.readme}{READ.ME}{aaareadme.txt}{README}{read-this-
  12591. first}} When a list is given, it is searched from left to right
  12592. and the first file found is displayed. The default list for UNIX
  12593. is:
  12594. {{./.readme}{README.TXT}{READ.ME}}
  12595. 9.1. Command Line Personalities
  12596. Beginning in version 7.0, if the C-Kermit binary is renamed to "telnet"
  12597. (or TELNET.EXE, telnet.pr, etc, depending on the platform), it accepts
  12598. the Telnet command line:
  12599. telnet [ host [ port ] ]
  12600. In Unix, you can achieve the same effect with a symlink:
  12601. cd /usr/bin
  12602. mv telnet oldtelnet
  12603. ln -ls /usr/local/bin/kermit telnet
  12604. When installed in this manner, C-Kermit always reads its initialization
  12605. file. If no host (and therefore no port) is given, C-Kermit starts in
  12606. interactive prompting mode. If a host is given as the first
  12607. command-line argument, C-Kermit makes a connection to it. The host
  12608. argument can be an IP host name or address, or the name of a TCP/IP
  12609. entry in your C-Kermit network directory.
  12610. If a port is given, it is used. If a port is not given, then if the
  12611. hostname was found in your network directory and port was also listed
  12612. there, then that port is used. Otherwise port 23 (the Telnet port) is
  12613. used.
  12614. When C-Kermit is called "telnet" and it is invoked with a hostname on
  12615. the command line, it exits automatically when the connection is closed.
  12616. While the connection is open, however, you may escape back and forth as
  12617. many times as you like, transfer files, etc.
  12618. An rlogin personality is also available, but it is less useful, at
  12619. least in UNIX and VMS, where the Rlogin TCP port is privileged.
  12620. The new variable \v(name) indicates the name with which C-Kermit was
  12621. invoked ("kermit", "wermit", "k95", "telnet", etc).
  12622. 9.2. Built-in Help for Command Line Options
  12623. "kermit -h", given from the system prompt, lists as many command-line
  12624. options as will fit on a standard 24x80 screen. For more comprehensive
  12625. help, use the interactive HELP OPTIONS command that was added in
  12626. C-Kermit 7.0:
  12627. HELP OPTIONS
  12628. Explains how command-line options work, their syntax, etc.
  12629. HELP OPTIONS ALL
  12630. Lists all command-line options and gives brief help about each one.
  12631. HELP OPTION x
  12632. Gives brief help about option "x".
  12633. HELP EXTENDED-OPTIONS
  12634. Lists the available extended-format command-line options.
  12635. HELP EXTENDED-OPTION xxx
  12636. Gives help for the specified extended option.
  12637. 9.3. New Command-Line Options
  12638. Command-line options added since C-Kermit 6.0 are:
  12639. +
  12640. (plus sign by itself): The next argument is the name of a script
  12641. to execute; all subsequent arguments are ignored by C-Kermit
  12642. itself, but passed to the script as top-level copies of \%1,
  12643. \%2, etc; the \&_[] is also set accordingly. \%0 and \&_[0]
  12644. become the name of the script file, rather than the pathname of
  12645. the C-Kermit program, which is its normal value. Primarily for
  12646. use in the top line of "Kerbang" scripts in UNIX (see
  12647. Section 7.19). Example from UNIX command line:
  12648. $ kermit [ regular kermit args ] + filename
  12649. Sample first line of Kerbang script:
  12650. #!/usr/local/bin/kermit +
  12651. --
  12652. (two hyphens surrounded by whitespace) Equivalent to "=", for
  12653. compatibility with UNIX getopt(1,3).
  12654. -G
  12655. GET (like -g), but send the incoming file to standard output.
  12656. Example: "kermit -G oofa.txt | lpr" retrieves a file from your
  12657. local computer (providing it is running a Kermit program that
  12658. supports the autodownload feature and has it enabled) and prints
  12659. it.
  12660. -O
  12661. equivalent to -x (start up in server mode), but exits after the
  12662. first client command has been executed (mnemonic: O = Only One).
  12663. This one is handy replacing "kermit -x" in the "automatically
  12664. start Kermit on the other end" string:
  12665. set protocol kermit {kermit -ir} {kermit -r} {kermit -x}
  12666. since -x leaves the remote Kermit in server mode after the
  12667. transfer, which can be confusing, whereas -O makes it go away
  12668. automatically after the transfer.
  12669. -L
  12670. Recursive, when used in combination with -s (mnemonic: L =
  12671. Levels). In UNIX or other environments where the shell expands
  12672. wildcards itself, the -s argument, if it contains wildcards,
  12673. must be quoted to prevent this, e.g.:
  12674. kermit -L -s "*.c"
  12675. In UNIX only, "kermit -L -s ." means to send the current
  12676. directory tree. SeeSections 4.10 and4.11 about
  12677. recursive file transfer.
  12678. -V
  12679. Equivalent to SET FILE PATTERNS OFF ( Section 4.3) and SET
  12680. TRANSFER MODE MANUAL. In other words, take the FILE TYPE setting
  12681. literally. For example, "kermit -VT oofa.bin" means send the
  12682. file in Text mode, no matter what its name is and no matter
  12683. whether a kindred spirit is recognized at the other end of the
  12684. connection.
  12685. -0
  12686. (digit zero) means "be 100% transparent in CONNECT mode". This
  12687. is equivalent to the following series of commands: SET PARITY
  12688. NONE, SET COMMAND BYTESIZE 8, SET TERMINAL BYTESIZE 8, SET FLOW
  12689. NONE, SET TERM ESCAPE DISABLED, SET TERM CHAR TRANSPARENT, SET
  12690. TERM AUTODOWNLOAD OFF, SET TERM APC OFF, SET TELOPT KERMIT
  12691. REFUSE REFUSE.
  12692. 10. C-KERMIT AND G-KERMIT
  12693. Every multifunctioned and long-lived software program grows in
  12694. complexity and size over time to meet the needs and requests of its
  12695. users and the demands of the underlying technology as it changes.
  12696. Eventually users begin to notice how big the application has grown, how
  12697. much disk space it occupies, how long it takes to load, and they start
  12698. to long for the good old days when it was lean and mean. Not long after
  12699. that they begin asking for a "light" version that only does the basics
  12700. with no frills.
  12701. And so it is with C-Kermit. A "light" version of Kermit was released
  12702. (for UNIX only) in December 1999 under the GNU General Public License;
  12703. thus it is called G-Kermit (for GNU Kermit). All it does is send and
  12704. receive files, period. You can find it at:
  12705. http://www.columbia.edu/kermit/gkermit.html
  12706. Where the C-Kermit 7.0 binary might be anywhere from 1 to 3 million
  12707. bytes in size, the G-Kermit binary ranges from 30K to 100K, depending
  12708. on the underlying architecture (RISC vs CISC, etc).
  12709. G-Kermit and C-Kermit may reside side-by-side on the same computer.
  12710. G-Kermit does not make connections; it does not have a script language;
  12711. it does not translate character sets. G-Kermit may be used instead of
  12712. C-Kermit when:
  12713. * It is on the remote end.
  12714. * Files are to be transferred in binary mode or in text mode without
  12715. character-set translation.
  12716. * File timestamps don't need to be preserved.
  12717. In such cases G-Kermit might be preferred since it generally starts up
  12718. faster, and yet transfers files just as fast on most (but not
  12719. necessarily all) kinds of connections; for example, it supports
  12720. streaming ( Section 4.20).
  12721. G-Kermit is also handy for bootstrapping. It is easier to load on a new
  12722. computer than C-Kermit -- it fits on a floppy diskette with plenty of
  12723. room to spare. Thus if you have (say) an old PC running (say) SCO Xenix
  12724. and no network connection, you can download the Xenix version of
  12725. G-Kermit to (say) a DOS or Windows PC, copy it to diskette, read the
  12726. diskette on Xenix with "dosread", and then use G-Kermit to receive
  12727. C-Kermit (which does not fit on a diskette). If diskettes aren't an
  12728. option, other bootstrapping methods are possible too -- see the
  12729. G-Kermit web page for details.
  12730. III. APPENDICES
  12731. III.1. Character Set Tables
  12732. III.1.1. The Hewlett Packard Roman8 Character Set
  12733. dec col/row oct hex description
  12734. 160 10/00 240 A0 (Undefined)
  12735. 161 10/01 241 A1 A grave
  12736. 162 10/02 242 A2 A circumflex
  12737. 163 10/03 243 A3 E grave
  12738. 164 10/04 244 A4 E circumflex
  12739. 165 10/05 245 A5 E diaeresis
  12740. 166 10/06 246 A6 I circumflex
  12741. 167 10/07 247 A7 I diaeresis
  12742. 168 10/08 250 A8 Acute accent
  12743. 169 10/09 251 A9 Grave accent
  12744. 170 10/10 252 AA Circumflex accent
  12745. 171 10/11 253 AB Diaeresis
  12746. 172 10/12 254 AC Tilde accent
  12747. 173 10/13 255 AD U grave
  12748. 174 10/14 256 AE U circumflex
  12749. 175 10/15 257 AF Lira symbol
  12750. 176 11/00 260 B0 Top bar (macron)
  12751. 177 11/01 261 B1 Y acute
  12752. 178 11/02 262 B2 y acute
  12753. 179 11/03 263 B3 Degree Sign
  12754. 180 11/04 264 B4 C cedilla
  12755. 181 11/05 265 B5 c cedilla
  12756. 182 11/06 266 B6 N tilde
  12757. 183 11/07 267 B7 n tilde
  12758. 184 11/08 270 B8 Inverted exclamation mark
  12759. 185 11/09 271 B9 Inverted question mark
  12760. 186 11/10 272 BA Currency symbol
  12761. 187 11/11 273 BB Pound sterling symbol
  12762. 188 11/12 274 BC Yen symbol
  12763. 189 11/13 275 BD Paragraph
  12764. 190 11/14 276 BE Florin (Guilder) symbol
  12765. 191 11/15 277 BF Cent symbol
  12766. 192 12/00 300 C0 a circumflex
  12767. 193 12/01 301 C1 e circumflex
  12768. 194 12/02 302 C2 o circumflex
  12769. 195 12/03 303 C3 u circumflex
  12770. 196 12/04 304 C4 a acute
  12771. 197 12/05 305 C5 e acute
  12772. 198 12/06 306 C6 o acute
  12773. 199 12/07 307 C7 u acute
  12774. 200 12/08 310 C8 a grave
  12775. 201 12/09 311 C9 e grave
  12776. 202 12/10 312 CA o grave
  12777. 203 12/11 313 CB u grave
  12778. 204 12/12 314 CC a diaeresis
  12779. 205 12/13 315 CD e diaeresis
  12780. 206 12/14 316 CE o diaeresis
  12781. 207 12/15 317 CF u diaeresis
  12782. 208 13/00 320 D0 A ring
  12783. 209 13/01 321 D1 i circumflex
  12784. 210 13/02 322 D2 O with stroke
  12785. 211 13/03 323 D3 AE digraph
  12786. 212 13/04 324 D4 a ring
  12787. 213 13/05 325 D5 i acute
  12788. 214 13/06 326 D6 o with stroke
  12789. 215 13/07 327 D7 ae digraph
  12790. 216 13/08 330 D8 A diaeresis
  12791. 217 13/09 331 D9 i grave
  12792. 218 13/10 332 DA O diaeresis
  12793. 219 13/11 333 DB U diaeresis
  12794. 220 13/12 334 DC E acute
  12795. 221 13/13 335 DD i diaeresis
  12796. 222 13/14 336 DE German sharp s
  12797. 223 13/15 337 DF O circumflex
  12798. 224 14/00 340 E0 A acute
  12799. 225 14/01 341 E1 A tilde
  12800. 226 14/02 342 E2 a tilde
  12801. 227 14/03 343 E3 Icelandic Eth
  12802. 228 14/04 344 E4 Icelandic eth
  12803. 229 14/05 345 E5 I acute
  12804. 230 14/06 346 E6 I grave
  12805. 231 14/07 347 E7 O acute
  12806. 232 14/08 350 E8 O grave
  12807. 233 14/09 351 E9 O tilde
  12808. 234 14/10 352 EA o tilde
  12809. 235 14/11 353 EB S caron
  12810. 236 14/12 354 EC s caron
  12811. 237 14/13 355 ED U acute
  12812. 238 14/14 356 EE Y diaeresis
  12813. 239 14/15 357 EF y diaeresis
  12814. 240 15/00 360 F0 Icelandic Thorn
  12815. 241 15/01 361 F1 Icelandic thorn
  12816. 242 15/02 362 F2 Middle dot
  12817. 243 15/03 363 F3 Greek mu
  12818. 244 15/04 364 F4 Pilcrow sign
  12819. 245 15/05 365 F5 Fraction 3/4
  12820. 246 15/06 366 F6 Long dash, horizontal bar
  12821. 247 15/07 367 F7 Fraction 1/4
  12822. 248 15/08 370 F8 Fraction 1/2
  12823. 249 15/09 371 F9 Feminine ordinal
  12824. 250 15/10 372 FA Masculine ordinal
  12825. 251 15/11 373 FB Left guillemot
  12826. 252 15/12 374 FC Solid box
  12827. 253 15/13 375 FD Right guillemot
  12828. 254 15/14 376 FE Plus or minus sign
  12829. 255 15/15 377 FF (Undefined)
  12830. III.1.2. Greek Character Sets
  12831. III.1.2.1. The ISO 8859-7 Latin / Greek Alphabet = ELOT 928
  12832. dec col/row oct hex description
  12833. 160 10/00 240 A0 No-break space
  12834. 161 10/01 241 A1 Left single quotation mark
  12835. 162 10/02 242 A2 right single quotation mark
  12836. 163 10/03 243 A3 Pound sign
  12837. 164 10/04 244 A4 (UNUSED)
  12838. 165 10/05 245 A5 (UNUSED)
  12839. 166 10/06 246 A6 Broken bar
  12840. 167 10/07 247 A7 Paragraph sign
  12841. 168 10/08 250 A8 Diaeresis (Dialytika)
  12842. 169 10/09 251 A9 Copyright sign
  12843. 170 10/10 252 AA (UNUSED)
  12844. 171 10/11 253 AB Left angle quotation
  12845. 172 10/12 254 AC Not sign
  12846. 173 10/13 255 AD Soft hyphen
  12847. 174 10/14 256 AE (UNUSED)
  12848. 175 10/15 257 AF Horizontal bar (Parenthetiki pavla)
  12849. 176 11/00 260 B0 Degree sign
  12850. 177 11/01 261 B1 Plus-minus sign
  12851. 178 11/02 262 B2 Superscript two
  12852. 179 11/03 263 B3 Superscript three
  12853. 180 11/04 264 B4 Accent (tonos)
  12854. 181 11/05 265 B5 Diaeresis and accent (Dialytika and Tonos)
  12855. 182 11/06 266 B6 Alpha with accent
  12856. 183 11/07 267 B7 Middle dot (Ano Teleia)
  12857. 184 11/08 270 B8 Epsilon with accent
  12858. 185 11/09 271 B9 Eta with accent
  12859. 186 11/10 272 BA Iota with accent
  12860. 187 11/11 273 BB Right angle quotation
  12861. 188 11/12 274 BC Omicron with accent
  12862. 189 11/13 275 BD One half
  12863. 190 11/14 276 BE Upsilon with accent
  12864. 191 11/15 277 BF Omega with accent
  12865. 192 12/00 300 C0 iota with diaeresis and accent
  12866. 193 12/01 301 C1 Alpha
  12867. 194 12/02 302 C2 Beta
  12868. 195 12/03 303 C3 Gamma
  12869. 196 12/04 304 C4 Delta
  12870. 197 12/05 305 C5 Epsilon
  12871. 198 12/06 306 C6 Zeta
  12872. 199 12/07 307 C7 Eta
  12873. 200 12/08 310 C8 Theta
  12874. 201 12/09 311 C9 Iota
  12875. 202 12/10 312 CA Kappa
  12876. 203 12/11 313 CB Lamda
  12877. 204 12/12 314 CC Mu
  12878. 205 12/13 315 CD Nu
  12879. 206 12/14 316 CE Ksi
  12880. 207 12/15 317 CF Omicron
  12881. 208 13/00 320 D0 Pi
  12882. 209 13/01 321 D1 Rho
  12883. 210 13/02 322 D2 (UNUSED)
  12884. 211 13/03 323 D3 Sigma
  12885. 212 13/04 324 D4 Tau
  12886. 213 13/05 325 D5 Upsilon
  12887. 214 13/06 326 D6 Phi
  12888. 215 13/07 327 D7 Khi
  12889. 216 13/08 330 D8 Psi
  12890. 217 13/09 331 D9 Omega
  12891. 218 13/10 332 DA Iota with diaeresis
  12892. 219 13/11 333 DB Upsilon with diaeresis
  12893. 220 13/12 334 DC alpha with accent
  12894. 221 13/13 335 DD epsilon with accent
  12895. 222 13/14 336 DE eta with accent
  12896. 223 13/15 337 DF iota with accent
  12897. 224 14/00 340 E0 upsilon with diaeresis and accent
  12898. 225 14/01 341 E1 alpha
  12899. 226 14/02 342 E2 beta
  12900. 227 14/03 343 E3 gamma
  12901. 228 14/04 344 E4 delta
  12902. 229 14/05 345 E5 epsilon
  12903. 230 14/06 346 E6 zeta
  12904. 231 14/07 347 E7 eta
  12905. 232 14/08 350 E8 theta
  12906. 233 14/09 351 E9 iota
  12907. 234 14/10 352 EA kappa
  12908. 235 14/11 353 EB lamda
  12909. 236 14/12 354 EC mu
  12910. 237 14/13 355 ED nu
  12911. 238 14/14 356 EE ksi
  12912. 239 14/15 357 EF omicron
  12913. 240 15/00 360 F0 pi
  12914. 241 15/01 361 F1 rho
  12915. 242 15/02 362 F2 terminal sigma
  12916. 243 15/03 363 F3 sigma
  12917. 244 15/04 364 F4 tau
  12918. 245 15/05 365 F5 upsilon
  12919. 246 15/06 366 F6 phi
  12920. 247 15/07 367 F7 khi
  12921. 248 15/08 370 F8 psi
  12922. 249 15/09 371 F9 omega
  12923. 250 15/10 372 FA iota with diaeresis
  12924. 251 15/11 373 FB upsilon with diaeresis
  12925. 252 15/12 374 FC omicron with diaeresis
  12926. 253 15/13 375 FD upsilon with accent
  12927. 254 15/14 376 FE omega with accent
  12928. 255 15/15 377 FF (UNUSED)
  12929. III.1.2.2. The ELOT 927 Character Set
  12930. dec col/row oct hex description
  12931. 32 02/00 40 20 SPACE
  12932. 33 02/01 41 21 EXCLAMATION MARK
  12933. 34 02/02 42 22 QUOTATION MARK
  12934. 35 02/03 43 23 NUMBER SIGN
  12935. 36 02/04 44 24 DOLLAR SIGN
  12936. 37 02/05 45 25 PERCENT SIGN
  12937. 38 02/06 46 26 AMPERSAND
  12938. 39 02/07 47 27 APOSTROPHE
  12939. 40 02/08 50 28 LEFT PARENTHESIS
  12940. 41 02/09 51 29 RIGHT PARENTHESIS
  12941. 42 02/10 52 2A ASTERISK
  12942. 43 02/11 53 2B PLUS SIGN
  12943. 44 02/12 54 2C COMMA
  12944. 45 02/13 55 2D HYPHEN, MINUS SIGN
  12945. 46 02/14 56 2E PERIOD, FULL STOP
  12946. 47 02/15 57 2F SOLIDUS, SLASH
  12947. 48 03/00 60 30 DIGIT ZERO
  12948. 49 03/01 61 31 DIGIT ONE
  12949. 50 03/02 62 32 DIGIT TWO
  12950. 51 03/03 63 33 DIGIT THREE
  12951. 52 03/04 64 34 DIGIT FOUR
  12952. 53 03/05 65 35 DIGIT FIVE
  12953. 54 03/06 66 36 DIGIT SIX
  12954. 55 03/07 67 37 DIGIT SEVEN
  12955. 56 03/08 70 38 DIGIT EIGHT
  12956. 57 03/09 71 39 DIGIT NINE
  12957. 58 03/10 72 3A COLON
  12958. 59 03/11 73 3B SEMICOLON
  12959. 60 03/12 74 3C LESS-THAN SIGN, LEFT ANGLE BRACKET
  12960. 61 03/13 75 3D EQUALS SIGN
  12961. 62 03/14 76 3E GREATER-THAN SIGN, RIGHT ANGLE BRACKET
  12962. 63 03/15 77 3F QUESTION MARK
  12963. 64 04/00 100 40 COMMERCIAL AT SIGN
  12964. 65 04/01 101 41 CAPITAL LETTER A
  12965. 66 04/02 102 42 CAPITAL LETTER B
  12966. 67 04/03 103 43 CAPITAL LETTER C
  12967. 68 04/04 104 44 CAPITAL LETTER D
  12968. 69 04/05 105 45 CAPITAL LETTER E
  12969. 70 04/06 106 46 CAPITAL LETTER F
  12970. 71 04/07 107 47 CAPITAL LETTER G
  12971. 72 04/08 110 48 CAPITAL LETTER H
  12972. 73 04/09 111 49 CAPITAL LETTER I
  12973. 74 04/10 112 4A CAPITAL LETTER J
  12974. 75 04/11 113 4B CAPITAL LETTER K
  12975. 76 04/12 114 4C CAPITAL LETTER L
  12976. 77 04/13 115 4D CAPITAL LETTER M
  12977. 78 04/14 116 4E CAPITAL LETTER N
  12978. 79 04/15 117 4F CAPITAL LETTER O
  12979. 80 05/00 120 50 CAPITAL LETTER P
  12980. 81 05/01 121 51 CAPITAL LETTER Q
  12981. 82 05/02 122 52 CAPITAL LETTER R
  12982. 83 05/03 123 53 CAPITAL LETTER S
  12983. 84 05/04 124 54 CAPITAL LETTER T
  12984. 85 05/05 125 55 CAPITAL LETTER U
  12985. 86 05/06 126 56 CAPITAL LETTER V
  12986. 87 05/07 127 57 CAPITAL LETTER W
  12987. 88 05/08 130 58 CAPITAL LETTER X
  12988. 89 05/09 131 59 CAPITAL LETTER Y
  12989. 90 05/10 132 5A CAPITAL LETTER Z
  12990. 91 05/11 133 5B LEFT SQUARE BRACKET
  12991. 92 05/12 134 5C REVERSE SOLIDUS, BACKSLASH
  12992. 93 05/13 135 5D RIGHT SQUARE BRACKET
  12993. 94 05/14 136 5E CIRCUMFLEX ACCENT
  12994. 95 05/15 137 5F UNDERSCORE
  12995. 96 06/00 140 60 ACCENT GRAVE
  12996. 97 06/01 141 61 GREEK LETTER ALPHA
  12997. 98 06/02 142 62 GREEK LETTER BETA
  12998. 99 06/03 143 63 GREEK LETTER GAMMA
  12999. 100 06/04 144 64 GREEK LETTER DELTA
  13000. 101 06/05 145 65 GREEK LETTER EPSILON
  13001. 102 06/06 146 66 GREEK LETTER ZETA
  13002. 103 06/07 147 67 GREEK LETTER ETA
  13003. 104 06/08 150 68 GREEK LETTER THETA
  13004. 105 06/09 151 69 GREEK LETTER IOTA
  13005. 106 06/10 152 6A GREEK LETTER KAPPA
  13006. 107 06/11 153 6B GREEK LETTER LAMDA
  13007. 108 06/12 154 6C GREEK LETTER MU
  13008. 109 06/13 155 6D GREEK LETTER NU
  13009. 110 06/14 156 6E GREEK LETTER KSI
  13010. 111 06/15 157 6F GREEK LETTER OMICRON
  13011. 112 07/00 160 70 GREEK LETTER PI
  13012. 113 07/01 161 71 GREEK LETTER RHO
  13013. 114 07/02 162 72 GREEK LETTER SIGMA
  13014. 115 07/03 163 73 GREEK LETTER TAU
  13015. 116 07/04 164 74 GREEK LETTER UPSILON
  13016. 117 07/05 165 75 GREEK LETTER FI
  13017. 118 07/06 166 76 GREEK LETTER XI
  13018. 119 07/07 167 77 GREEK LETTER PSI
  13019. 120 07/08 170 78 GREEK LETTER OMEGA
  13020. 121 07/09 171 79 SPACE
  13021. 122 07/10 172 7A SPACE
  13022. 123 07/11 173 7B LEFT CURLY BRACKET, LEFT BRACE
  13023. 124 07/12 174 7C VERTICAL LINE, VERTICAL BAR
  13024. 125 07/13 175 7D RIGHT CURLY BRACKET, RIGHT BRACE
  13025. 126 07/14 176 7E TILDE
  13026. 127 07/15 177 7F RUBOUT, DELETE
  13027. III.1.2.3. PC Code Page 869
  13028. (to be filled in...)
  13029. III.2. Updated Country Codes
  13030. Date: Mon, 7 Apr 1997 23:23:49 EDT
  13031. From: Dave Leibold <dleibold@else.net>
  13032. Newsgroups: comp.dcom.telecom
  13033. Subject: Ex-USSR Country Codes Profile
  13034. Organization: TELECOM Digest
  13035. Ex-USSR Country Codes Profile
  13036. 4 April 1997
  13037. Below is a summary of the country codes that have formed in the wake of
  13038. the USSR dissolution, along with some updated findings and reports.
  13039. Additional or corrected information on any of these nations would be
  13040. welcome (c/o dleibold@else.net).
  13041. * Kyrgyz Republic country code 996 will take effect, at least in
  13042. Canada, effective 1 May 1997, according to CRTC Telecom Order
  13043. 97-464, based on Stentor Tariff Notice 433. There is no indication
  13044. whether there will be a permissive dialing period involved or for
  13045. how long such a permissive operation would remain.
  13046. * Country code 992 was reported as a recent assignment for
  13047. Tajikistan, which will be moving from country code 7 at some
  13048. unknown time.
  13049. * Uzbekistan has its own country code assignment, but I have no
  13050. information if this is in service yet or what implementation dates
  13051. have been set.
  13052. * Kazakstan does not have a known separate country code assignment at
  13053. present. It remains in country code 7 for the time being.
  13054. * Russia seems destined to keep country code 7.
  13055. * Recent news reports speak of some agreements forming between Russia
  13056. and Belarus. While there is no outright reunification yet, there is
  13057. expected to be much closer ties between the two nations. Whether
  13058. this will lead to a reunification of telephone codes remains to be
  13059. seen.
  13060. In the table, "Effective" means the date at which the country code
  13061. began service (which could vary according to the nation). "Mandatory"
  13062. means the date at which the country code 7 is invalid for calls to that
  13063. nation. There are a number of question marks since exact dates have not
  13064. been collected in all cases.
  13065. CC Nation Effective Mandatory Notes
  13066. 370 Lithuania 1993? ??? Announced Jan 1993
  13067. 371 Latvia 1993? ???
  13068. 372 Estonia 1 Feb 1993? March 1993?
  13069. 373 Moldova 1993? ??? Announced Jan 1993
  13070. 374 Armenia 1 May 1995 1 July 1995 Announced Jan 1995 (ITU)
  13071. 375 Belarus 16 Apr 1995 1997?
  13072. 380 Ukraine 16 Apr 1995 Oct 1995?
  13073. 7 Kazakstan (no known changes)
  13074. 7 Russia (presumably not changing)
  13075. 992 Tajikistan ??? ??? Announced 1996-7?
  13076. 993 Turkmenistan 3 Jan 1997 3 Apr 1997 Canada as of 29 Nov 1996
  13077. 994 Azerbaijan Sept 1994? ??? Announced 1992
  13078. 995 Georgia 1994? ??? ref: Telecom Digest Oct 1994
  13079. 996 Kyrgyz Republic 1 May 1997 ??? ref: Stentor Canada/CRTC
  13080. 998 Uzbekistan ??? ??? Announced 1996? (ITU)
  13081. Details courtesy Toby Nixon, ITU, Stentor (Canada), CRTC (Canada),
  13082. TELECOM Digest (including information collected for the country code
  13083. listings).
  13084. IV. ERRATA & CORRIGENDA
  13085. The following errors inUsing C-Kermit, Second Edition, first
  13086. printing, have been noted.
  13087. First, some missing acknowledgements for C-Kermit 6.0: JE Jones of
  13088. Microware for help with OS-9, Nigel Roles for his help with Plan 9,
  13089. Lucas Hart for help with VMS and Digital UNIX, Igor Kovalenko for his
  13090. help with QNX. And later, to Susan Kleinmann for her help with Debian
  13091. Linux packaging; Patrick Volkerding for his help with Slackware Linux
  13092. packaging; Jim Knoble for his help with Red Hat Linux packaging; and to
  13093. dozens of others for sending individual C-Kermit binaries for varied
  13094. and diverse platforms.
  13095. Thanks to James Spath for both binaries and reporting many of the typos
  13096. noted below. Also to Dat Thuc Nguyen for spotting several typos.
  13097. PAGE REMARKS
  13098. COVER "COS" is a misprint. There is no COS. Pretend it says "SCO" or "VOS".
  13099. (This is fixed in the second printing.)
  13100. xxi Second line: Fred Smith's affiliation should be Computrition.
  13101. 83 Change "commands other" to "commands as other" (1st paragraph)
  13102. 87 Change "The the" to "The" (2nd paragraph)
  13103. 92 "set modem-type user-defined supra" should be "set modem type ..."
  13104. 95 Change "VI" to "vi" (1st paragraph)
  13105. 96 Change "it it" to "it is" (1st paragraph)
  13106. 97 Change "advantage a literal" to "advantage of a literal" (2nd
  13107. paragraph)
  13108. 102 The call-waiting example would be better as SET DIAL PREFIX *70W
  13109. (rather than "*70,") because the former will not cause an incorrect
  13110. call to be placed with pulse dialing.
  13111. 123 Third paragraph from bottom: "..otherwise if a your local username.."
  13112. should be "..otherwise your local username..".
  13113. 160 Delete the "it" between "and" and "to" (2nd paragraph)
  13114. 185 In "When TRANSFER DISPLAY is OFF, C-Kermit skips the display...",
  13115. "OFF" should be "NONE".
  13116. 187 The last paragraph says the "A command" is ignored, should be "S".
  13117. 194 Change "it known" to "it is known" (4th paragraph).
  13118. 235 In C-Kermit 7.0, the syntax of the GET command changed. MGET now
  13119. must be used to get a list of files and there is no more multiline
  13120. GET command.
  13121. 268 Last paragraph: "effect" should be "affect".
  13122. 275 In the SET PROTOCOL KERMIT description, the following sentence is
  13123. incorrect and should be removed: 'If you omit the commands, the
  13124. default ones are restored: "kermit -ir" and "kermit -r" respectively".
  13125. The correct information is given at the bottom of page 281.
  13126. 279 9th line. The decimal value of ST is 156, not 155.
  13127. 295 In the stepping stones, skip ahead to Chapter 17 on p. 327.
  13128. 298 Table 16-2, Portuguese entry. Column 4/00 should show section sign,
  13129. not acute accent.
  13130. 316 Other languages written in the Hebrew alphabet include Karaim (a Turkic
  13131. language spoken in Lithuania and Poland), Judeo-Kurdish, and Judeo-
  13132. Georgian.
  13133. 332 UNDEFINE definition, change "This just" to "This is just".
  13134. 344 It might be necessary to set the modem's pulse generation rate when
  13135. sending numeric pages; most Hayes compatible modems use the S11
  13136. register for this.
  13137. 350 Delete "is" from between "It" and "ceases" (4th paragraph)
  13138. 351 Top - both occurrences of "print \%a" should be "echo \%a".
  13139. 364 \v(input) and \v(query) out of alphabetical order.
  13140. 378 In the MYSEND macro, "if not \m(rc) goto bad" should be:
  13141. "if \m(rc) goto bad" (remove the "not").
  13142. 382-383 It should be stated that the loop control variable must be of the \%a
  13143. type, or else an array element; macro names can not be used for this.
  13144. 383 In line 3, "\%f[\%i]" should be "\&f[\%i]".
  13145. 383 In the sort example, it should be stated that the array is 1-based.
  13146. 387 Change "You can list" to "You can get a list" (5th paragraph)
  13147. 393 \Fverify() description. The 3rd sentence could be stated more clearly
  13148. as "If all characters in string2 are also in string1, 0 is returned."
  13149. 398 Copying \ffiles() results to an array before is not required as of
  13150. C-Kermit 7.0 (see Section 7.3).
  13151. 403 In "(\%a + 3) * (\%b 5)", a minus sign is missing between b and 5.
  13152. 407 C-Kermit 7.0 no longer supports multiline GET. Change
  13153. "get, \%1, \%2" to "get {\%1} {\%2}" or "get /as:{\%2} {\%1}".
  13154. 409 READ example while loop should be:
  13155. while success { echo \m(line), read line }
  13156. 409 "WRITE file" should be "WRITE keyword" (you can't put a filename there)
  13157. (The same applies to WRITE-LINE / WRITELN).
  13158. 414 \Funhexify() missing from Table 18-3.
  13159. 425 MINPUT definition, change 2nd "text2" to "text3".
  13160. 436 Several lines are missing from the UNIXLOGIN macro listing.
  13161. After the "xif fail" block, insert:
  13162. out \%1\13 ; Send username, carriage return
  13163. inp 5 Password: ; Wait 5 sec for this prompt
  13164. if fail end 1 No password prompt
  13165. pause ; Wait a sec
  13166. out \%2\13 ; Send password
  13167. 440 Change "set terminal byteszie" to "set terminal bytesize".
  13168. Change "input Password:" to "input 10 Password".
  13169. 448 Franchise script: "access line" should be "access \m(line)".
  13170. 453 There are two incorrectly coded IF statements in the DELIVER macro
  13171. definition. Replace both occurrences of "if > \%1 \%3 {" with
  13172. "xif > \%i \%3 {" (replace "if" by "xif" and "\%1" with "\%i").
  13173. 453 "the the" (last paragraph) should be "the".
  13174. 454 EOT (last paragraph) is End of Transmission, not End of Text.
  13175. 457 _DEFINE definition: "name constructed" should be "name is constructed".
  13176. 457 "macro for and" (last paragraph) should be "macro and".
  13177. 459 Should explain that \v(user) is a legal abbreviation of \v(userid).
  13178. 480 Figure II-2 is backwards; the least-significant bit is transmitted
  13179. first, then up to the highest, and the parity bit last.
  13180. 534 The VMS Appendix section on Odd Record Lengths no longer applies;
  13181. C-Kermit 7.0 handles odd record lengths as well as even ones.
  13182. 559 Table VIII-3, Portuguese entry. Column 4/00 should show section sign,
  13183. not acute accent.
  13184. 560-563 HP-Roman8 missing from Table VII-4; there wasn't room to squeeze it in.
  13185. It is listed in section II(6).
  13186. 565 "d stroke" in Table VII-5 has the wrong appearance; the stem should
  13187. be upright. The letter shown in the table is actually a lowercase
  13188. Icelandic eth, which has a curved stem.
  13189. 601-604 BeBox, BeOS, Plan 9, and probably others not listed in trademarks.
  13190. 604 The words "SCRIBE TEXT FORMATTER" appear at the end of the last
  13191. sentence of the first paragraph of the Colophon. They should have
  13192. been in the Index.
  13193. Index: Missing entries: SET { SEND, RECEIVE } PATHNAMES, Call waiting, ...
  13194. \F() Page 605, add also 413-414
  13195. \Fbreak 389
  13196. \Fcapitalize 390
  13197. \Fchecksum 414
  13198. \Fcrc16 414
  13199. \Fexecute 414
  13200. \Fhexify 390
  13201. \Fltrim 391
  13202. \Frepeat 392
  13203. \Fspawn 392
  13204. \Ftod2secs 399
  13205. \v() built_in Page 606, add also 361-364
  13206. \v(_line) 354, 361
  13207. \v(apcactive) 361
  13208. \v(charset) 362
  13209. \v(cpu) 362
  13210. \v(crc16) 357, 362
  13211. \v(d$xxx) add page 362
  13212. \v(dialnumber) 362
  13213. \v(dialresult) 362
  13214. \v(errno) 362
  13215. \v(errstring) 362
  13216. \v(exedir) 362
  13217. \v(inidir) 363
  13218. \v(ipaddress) 363
  13219. \v(keyboard) 363
  13220. \v(macro) 363
  13221. \v(minput) 363
  13222. \v(m_xxx) 94, 363
  13223. \v(password) 364
  13224. \v(query) 364
  13225. \v(prompt) 364
  13226. \v(speed) 356, 364
  13227. \v(startup) 364
  13228. \v(status) 364
  13229. \v(sysid) 364
  13230. \v(system) 364
  13231. \v(fsize) at lower half page 606 should read \v(tfsize)
  13232. \v(xversion) 364
  13233. BEEP Command 40
  13234. SET FLOW 62, 212
  13235. Figure II-5 on page 493. The pin assignments of the Mini Din-8
  13236. connector are not described anywhere. As noted in the text, these tend
  13237. to vary from vendor to vendor. One common arrangement is:
  13238. 1. HSKout (Handshake out -- definition depends on software)
  13239. 2. HSKin (Handshake in or external clock)
  13240. 3. TxD-
  13241. 4. Not used
  13242. 5. RxD-
  13243. 6. TxD+
  13244. 7. Not used
  13245. 8. RxD+
  13246. Note the "balanced pairs" for Receive Data (RxD) and Transmit Data
  13247. (TxD), and the utter lack of modem signals. These connectors follow the
  13248. RS-423 standard, rather than RS-232. In some arrangements, Pin 1 is
  13249. used for DTR and Pin 2 for CD; in others Pin 1 is RTS and Pin 2 is CTS.
  13250. Please send reports of other errors to the authors, as well as
  13251. suggestions for improvements, additional index entries, and any other
  13252. comments:
  13253. kermit@columbia.edu
  13254. APPENDIX V. ADDITIONAL COPYRIGHT NOTICES
  13255. The following copyrights cover some of the source code used in the
  13256. development of C-Kermit, Kermit 95, or Kermit 95 support libraries.
  13257. /*****************************************************************************/
  13258. /* */
  13259. /* Copyright (c) 1995 by Oy Online Solutions Ltd. */
  13260. /* */
  13261. /* Distribution of this source code is strictly forbidden. Use of this */
  13262. /* source code is granted to the University of Columbia C-Kermit project */
  13263. /* to be distributed in binary format only. Please familiarize yourself */
  13264. /* with the accompanying LICENSE.P file. */
  13265. /* */
  13266. /*****************************************************************************/
  13267. used for Xmodem, Ymodem, and Zmodem protocol in Kermit 95 (p95.dll,
  13268. p2.dll)
  13269. Copyright (c) 1997 Stanford University
  13270. The use of this software for revenue-generating purposes may require a
  13271. license from the owners of the underlying intellectual property.
  13272. Specifically, the SRP-3 protocol may not be used for revenue-generating
  13273. purposes without a license.
  13274. Within that constraint, permission to use, copy, modify, and distribute
  13275. this software and its documentation for any purpose is hereby granted
  13276. without fee, provided that the above copyright notices and this
  13277. permission notice appear in all copies of the software and related
  13278. documentation.
  13279. THE SOFTWARE IS PROVIDED "AS-IS" AND WITHOUT WARRANTY OF ANY KIND,
  13280. EXPRESS, IMPLIED OR OTHERWISE, INCLUDING WITHOUT LIMITATION, ANY
  13281. WARRANTY OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
  13282. IN NO EVENT SHALL STANFORD BE LIABLE FOR ANY SPECIAL, INCIDENTAL,
  13283. INDIRECT OR CONSEQUENTIAL DAMAGES OF ANY KIND, OR ANY DAMAGES
  13284. WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER OR NOT
  13285. ADVISED OF THE POSSIBILITY OF DAMAGE, AND ON ANY THEORY OF LIABILITY,
  13286. ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS
  13287. SOFTWARE.
  13288. Used for Secure Remote Password (TM) protocol (SRP) in C-Kermit, Kermit
  13289. 95 (k95.exe, k2.exe, k95crypt.dll, k2crypt.dll)
  13290. Copyright 1990 by the Massachusetts Institute of Technology. All Rights
  13291. Reserved.
  13292. Export of this software from the United States of America may require a
  13293. specific license from the United States Government. It is the
  13294. responsibility of any person or organization contemplating export to
  13295. obtain such a license before exporting.
  13296. WITHIN THAT CONSTRAINT, permission to use, copy, modify, and distribute
  13297. this software and its documentation for any purpose and without fee is
  13298. hereby granted, provided that the above copyright notice appear in all
  13299. copies and that both that copyright notice and this permission notice
  13300. appear in supporting documentation, and that the name of M.I.T. not be
  13301. used in advertising or publicity pertaining to distribution of the
  13302. software without specific, written prior permission. M.I.T. makes no
  13303. representations about the suitability of this software for any purpose.
  13304. It is provided "as is" without express or implied warranty.
  13305. Used for Telnet Authentication Option, Telnet Encryption Option, and
  13306. Kerberos (TM) authentication in C-Kermit, Kermit 95 (k95.exe, k2.exe,
  13307. k95crypt.dll, k2crypt.dll)
  13308. Copyright (c) 1991, 1993 The Regents of the University of California.
  13309. All rights reserved.
  13310. Redistribution and use in source and binary forms, with or without
  13311. modification, are permitted provided that the following conditions are
  13312. met:
  13313. 1. Redistributions of source code must retain the above copyright
  13314. notice, this list of conditions and the following disclaimer.
  13315. 2. Redistributions in binary form must reproduce the above copyright
  13316. notice, this list of conditions and the following disclaimer in the
  13317. documentation and/or other materials provided with the
  13318. distribution.
  13319. 3. All advertising materials mentioning features or use of this
  13320. software must display the following acknowledgement:
  13321. This product includes software developed by the University of
  13322. California, Berkeley and its contributors.
  13323. 4. Neither the name of the University nor the names of its
  13324. contributors may be used to endorse or promote products derived
  13325. from this software without specific prior written permission.
  13326. THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  13327. ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  13328. IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  13329. PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS
  13330. BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
  13331. CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
  13332. SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
  13333. BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
  13334. WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
  13335. OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
  13336. ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  13337. Used for Telnet Authentication Option, Telnet Encryption Option, and
  13338. Kerberos (TM) authentication in C-Kermit, Kermit 95 (k95.exe, k2.exe,
  13339. k95crypt.dll, k2crypt.dll)
  13340. Copyright (C) 1995-1997 Eric Young (eay@cryptsoft.com) All rights
  13341. reserved.
  13342. This package is an DES implementation written by Eric Young
  13343. (eay@cryptsoft.com). The implementation was written so as to conform
  13344. with MIT's libdes.
  13345. This library is free for commercial and non-commercial use as long as
  13346. the following conditions are aheared to. The following conditions apply
  13347. to all code found in this distribution.
  13348. Copyright remains Eric Young's, and as such any Copyright notices in
  13349. the code are not to be removed. If this package is used in a product,
  13350. Eric Young should be given attribution as the author of that the SSL
  13351. library. This can be in the form of a textual message at program
  13352. startup or in documentation (online or textual) provided with the
  13353. package.
  13354. Redistribution and use in source and binary forms, with or without
  13355. modification, are permitted provided that the following conditions are
  13356. met:
  13357. 1. Redistributions of source code must retain the copyright notice,
  13358. this list of conditions and the following disclaimer.
  13359. 2. Redistributions in binary form must reproduce the above copyright
  13360. notice, this list of conditions and the following disclaimer in the
  13361. documentation and/or other materials provided with the
  13362. distribution.
  13363. 3. All advertising materials mentioning features or use of this
  13364. software must display the following acknowledgement: This product
  13365. includes software developed by Eric Young (eay@cryptsoft.com)
  13366. THIS SOFTWARE IS PROVIDED BY ERIC YOUNG ``AS IS'' AND ANY EXPRESS OR
  13367. IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
  13368. WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
  13369. DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE FOR
  13370. ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  13371. DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  13372. OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  13373. HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
  13374. STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING
  13375. IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  13376. POSSIBILITY OF SUCH DAMAGE.
  13377. The license and distribution terms for any publically available version
  13378. or derivative of this code cannot be changed. i.e. this code cannot
  13379. simply be copied and put under another distribution license [including
  13380. the GNU Public License.]
  13381. The reason behind this being stated in this direct manner is past
  13382. experience in code simply being copied and the attribution removed from
  13383. it and then being distributed as part of other packages. This
  13384. implementation was a non-trivial and unpaid effort.
  13385. Used DES encryption in Kermit 95 (k95crypt.dll, k2crypt.dll)
  13386. __________________________________________________________________
  13387. * This is version 1.1 of CryptoLib
  13388. *
  13389. * The authors of this software are Jack Lacy, Don Mitchell and Matt Blaze
  13390. * Copyright (c) 1991, 1992, 1993, 1994, 1995 by AT&T.
  13391. * Permission to use, copy, and modify this software without fee
  13392. * is hereby granted, provided that this entire notice is included in
  13393. * all copies of any software which is or includes a copy or
  13394. * modification of this software and in all copies of the supporting
  13395. * documentation for such software.
  13396. *
  13397. * NOTE:
  13398. * Some of the algorithms in cryptolib may be covered by patents.
  13399. * It is the responsibility of the user to ensure that any required
  13400. * licenses are obtained.
  13401. *
  13402. *
  13403. * SOME PARTS OF CRYPTOLIB MAY BE RESTRICTED UNDER UNITED STATES EXPORT
  13404. * REGULATIONS.
  13405. *
  13406. *
  13407. * THIS SOFTWARE IS BEING PROVIDED "AS IS", WITHOUT ANY EXPRESS OR IMPLIED
  13408. * WARRANTY. IN PARTICULAR, NEITHER THE AUTHORS NOR AT&T MAKE ANY
  13409. * REPRESENTATION OR WARRANTY OF ANY KIND CONCERNING THE MERCHANTABILITY
  13410. * OF THIS SOFTWARE OR ITS FITNESS FOR ANY PARTICULAR PURPOSE.
  13411. Used for Big Number library in Kermit 95 (k95crypt.dll, k2crypt.dll).
  13412. __________________________________________________________________
  13413. CKERMIT70.TXT
  13414. The Kermit Project
  13415. Columbia University
  13416. 8 Feb 2000
  13417. Last update: 8 Aug 2011