-----------------------------------------------------------------------------
File name:	MT_X.DOC			Revision date:	1993.08.26
Revised by:	Ulf Ronald Andersson		Creation date:	1993.04.24
File purpose:	Document MichTron eXtension 4.	Version:	4.1
-----------------------------------------------------------------------------
NB: All text below is in Swedish.
-----------------------------------------------------------------------------
Introduktion:

Detta dokument brjade sin bana som ett personligt brev till Martin Hggbom,
sysop p Dataline BBS, vilket frklarar den informella stilen i vissa delar.

Brevet diskuterade olika aspekter av ett program benmnt "Resopen".
Det programmet gav fr frsta gngen Michtron 3.0 mjlighet att anropa
externa program, till priset av tillflligt avstngd multi-tasking.
Det senare gr dock inget i Dataline BBS, som ju bara nyttjar ett modem.

Martin hade allts bett mig att analysera programmet "ResOpen", med avseende
p eventuella risker med att installera detta i Dataline BBS.

Resultatet blev dock i stllet att jag skrev en ny variant p samma tema,
vilket naturligtvis blev MT_X, som allts erstter "ResOpen".
Den ursprungliga texten jag fick med till "ResOpen" beskriver allts i stort
ven hur MT_X fungerar, utom dr annat beskrivs i denna fil.

Nu tycker jag allts att det r dags att programmet fr en egen DOC-fil,
srskilt som jag nu gjort en del ndringar, och kanske gr fler senare.

-----------------------------------------------------------------------------
ndringar som skett mellan version 4.1 och 4.0 av MT_X:

Nr MT_X laddat in Michtron i minnet s kan den ndra de pekare och masker
som tidigare lste Michtron till sin interna font, och begrnsade den
anvndbara teckenuppsttningen.

Michtron kan drfr "adoptera" den aktuella systemfonten, som ocks kan
vara ndrad (av NVDI tex.), s att ven ANSI-grafik kan anvndas.
Michtron kan ocks tillta, och visa p den lokala skrmen, alla de
specialtecken som tidigare var frbjudna, som de svenska specialtecknen.

Motsvarande specialtangenter kan naturligtvis anvndas av Sysop,
vid arbete p BBS-konsollen, eller som lokalt inloggad.

Dessutom finns det mjlighet att filtrera in- och ut-matning, fr att kunna
verstta mellan olika teckenstandard (tex: svenska 7-bits resp 8-bits).
Det r naturligtvis helt separata, och oberoende filter fr inmatning
respektive utmatning.

Filtreringen kan ven sls till och frn, utan att ndra dess tabeller,
vilka ocks individuellt kan terstllas fr omprogrammering.

Dessa nya kommandon nyttjar samma metod som tidigare ("list"-kommando), men
med en enkelt utkad syntax.

OBS:
----
Fr att inte stra befintliga MCL-system, s r flertalet nya funktioner
frnslagna vid uppstart och mste aktiveras genom MCL-kommandon (list).
Enda undantaget r systemfonten och dess frmga att visa 8bits-koder,
eftersom det r ett vrdefullt tillskott s sysop kan se felaktigheter.
Dremot kan inga rutiner _hantera_ 8bits-koder frrn det sls p.

Syntaxen fr de nya kommandona beskrivs lngre fram i dokumentet.

-----------------------------------------------------------------------------
Hr fljer huvud dokumentet fr MT_X version 4.0:

Ja, d har jag ntligen ftt ndan ur vagnen och kollat RESOPEN t dig.
Ngra bakdrrar, eller liknande, finns hur som helst inte i programmet, men
jag hittade en del buggar och naturligtvis en del saker som var ineffektiva,
eftersom maskinkoden ju var skapad av en kompilator (Sozobon C).
Drfr skrev jag om programmet litet grann och dpte denna version till MT_X,
som allts str fr "MichTron eXtension", och nyttjar XBRA-kod "MTx4".
Fr att lttare kunna visa vad som ndrats har jag tagit med en del av DOC'en
i det hr brevet, dessa rader r samtliga indenterade med tv mellanslag.
Mina egna kommentarer och frklaringar brjar dremot i vnstermarginalen.

(NB: De flesta exempel frn den DOC som nmns r nu borttagna iom vers: 4.1)

-----------------------------------------------------------------------------
  Det som krvs fr att kra ResOpen r minst 1 Mb i datorn.

Nja, det borde nog g med mindre ocks, fast visst blir det trngt d iofs.

-----------------------------------------------------------------------------
  Resopen mste ligga i samma mapp som BBS.TOS (Mapp \BBS\) och man
  lgger de externa programmen man vill att Resopen skall starta dr ocks.

Nehepp, det ska inte alls behvas, utan det r s hr:

Mappen som innehller BBS.TOS, mste vara default-katalog (toppfnster tex.)
nr man startar MT_X (eller RESOPEN). (iofs praktiskt att ha dem tillsammans)
Vill man ha MT_X som desktop-ikon i TOS 2.06 s br den iofs ligga i samma
folder som BBS.TOS, och installeras med applikationens folder som default.
D kan man nmligen starta problemfritt oavsett vilka fnster som syns.

De externa programmen kan f ligga var man vill, fast d mste man frsts
ocks ange den fullstndiga skvgen fr att de ska hittas.

OBS: I MCL's _konstanta_ strngar mste "backslash" upprepas 2 ggr fr att f
     nskad effekt, men detta gller inte strngar som r _variabler_ utom
     nr man matar dem med strngkonstanter frsts.

Utan att ange ngon skvg s gller samma regel som fr BBS.TOS

-----------------------------------------------------------------------------
  Man startar BBS:en genom att klicka p ResOpen som i sin tur startar  
  BBS.TOS.

Det r samma sak med MT_X.PRG som med RESOPEN.TOS, bara s du vet det.

MT_X-programmet ska ha extension ".PRG" fr att kunna tillta Michtron att
anropa GEM-program p ett korrekt stt.
MT_X anvnder dock inte sjlv ngra GEM-anrop och kan drfr kras som ".TOS"
fast det d blir frbjudet att anropa GEM-program ifrn Michtron. 

-----------------------------------------------------------------------------
Hur gr man d fr att f MT_X att starta externa prg?

Man anvnder (precis som i ResOpen) MCL-kommandot "list" med
en srskild syntax som knns igen av den inlnkade gemdos-tolken.

Exempelvis s hr:
 
	list("loggfilnamn#programnamn#parametrar");
			 |
			 +-- detta tecken mste finnas, annars blir det inget
			     anrop, utan bara ett vanligt listkommando.

	'loggfilnamn' 	Filnamnet dr man vill logga info om anropet r
			valfritt, s inget lagras om namnet utelmnas.

	'#'		Detta tecken mste finnas fr att anrop ska ske.

	'programnam'	Filnamnet p programmet som ska kras (tnka sig!)

	'#'		Detta tecken krvs fr att f ha parametrar.

	'parametrar'	r de argument programmet ska kras med

Det r allts bara att bka ihop en strng med dessa bestndsdelar och
anvnda den strngen i "list"-kommandot.

Antag att jag har XYZ.TTP i C:\COMM\ och vill gra en download med
Zmodem till arean G:\BBS\UPLOADS\.  D kan jag gra s hr:

    list("#C:\\COMM\\XYZ.TTP#-d G:\\BBS\\UPLOADS\\");

Givetvis gr det lika bra att bka ihop strngen med variabler i stllet
fr strngkonstanter, det viktiga r ju vad den totala strngen innehller.

Om jag i stllet vill snda en fil, sg G:\GRAFIK\KAAKA.GIF, och ven
vill att anropet noteras i filen G:\BBS\LOGS\DL.LOG, s kr jag bara:

    list("g:\\bbs\\logs\\dl.log#c:\\comm\\xyz.ttp#-u g:\\grafik\\kaaka.gif");

Hr hade RESOPEN en bug som gjorde att loggfil-namnet inte anvndes,
utan att det alltid blev namnet "RUNOPEN.LOG" vad man n skrev.
Dessutom s raderade den en eventuell tidigare log_fil i stllet fr att
utka den med den nya informationen. (Radera kan man ju sjlv ju!)
Dessutom skapade den alltid filen, ven om man angivit tomt namn genom att
inleda med "#" direkt fljt av sitt programnamn.
Dessutom fanns det en felhantering av argumentet som kunde ge skrpargument
vid upprepade anrop dr vissa inte nyttjade argument (fatalt fr XYZ.TTP).

Alla dessa fel r rttade i MT_X.TOS .

-----------------------------------------------------------------------------
Hr r ett exempel med strngvariabler ocks:

	a$="PROG_LOG.LOG#";	Detta r loggfilen du vill ha info i
	b$="DITT.PRG#";		Detta r ditt program som du vill starta
	c$="parametrar";	Detta r parametrarna till ditt program
 
	strcat(a$,b$);		Hr laggs de ihop till en strng
	strcat(a$,c$);

 	list(a$);		Nu ger vi BBS.TOS kommandot List, vilket
				medfr att BBS.TOS skall ppna en fil, varvid
				MTx4 kollar om namnet innehller tecknet '#'.

Hr r dokumentationen till Resopen felaktig, och pstr att den kollar andra
saker ocks trots att den gr exakt samma sak, fast tyvrr med buggar.

				Om '#' hittas s tittar MTx4 p vad som str
				efter detta och startar detta prg med de
				parametrar som str efter nsta '#'

Hr hade Resopen en bugg som gjorde att program som ej skulle ha parametrar
nd fick en skrptext som argument.

				Slutligen kollar MTx4 p nytt om ngot stod
				fre det frsta '#'-tecknet, och i s fall
				ppnas en loggfil med detta namn & skvg,
				till vilken uppgifter om anropet lggs.

Resopen hade en bugg som gjorde att lagringen av logg-namnet blev felaktig,
varfr dess frfattare ersatte detta med ett fast namn = "RUNOPEN.LOG".
Pga av alla buggarna s lt frfattaren ocks radera filen varje gng, och
skrev mngder av systeminformation i den fr sina avbuggningsfrsk.
Drfr fanns det ingen fungerande logg-hantering i Resopen.

I MTx4 r buggarna borta, s det av anvndaren angivna namnet anvnds,
logg_filen skapas bara om den saknas, och raderna med ny info lggs till den.

Resopen hade ocks en bugg som gjorde att hanteringen inte alltid avslutades
korrekt, utan med att loggfilen listades.
Detta sker inte med MTx4.

-----------------------------------------------------------------------------
Utkade interna kommandon i version 4.1:
-----------------------------------------------------------------------------

Samtliga nya kommandon ges, som de ldre, via MCL's kommando "list" och har
ven samma tre definierade flt i argumentet.
Fr att ingen sammanblandning ska kunna ske mellan de interna kommandona och
anrop av externa program, s ska delstrngen fr programnamn alltid vara tom.

Det ger allts fljande syntax:

	list("kommando##argument");
		      ||
		      ++--Bda dessa tecken mste finnas, utan mellanrum.

De kommandon som finns idag bestr alltid av 2 tecken och krver ett enstaka
tecken som argument.  Avviker formatet frn detta utfrs inte kommandona.

De tta viktigaste kommandona r frsts de som kopplar in (eller bort) de
olika "patch"-rutinerna till Michtron.  De r som fljer

	list("PF##0");	Patchar bort systemfonten (kan ej visa 8bits kod)
	list("PF##1");	Patchar in systemfonten (Kan ven visa 8bits kod)
	list("P8##0");	Patchar bort 8-bits ascii-hantering
	list("P8##1");	Patchar in 8-bits ascii-hantering
	list("PI##0");	Patchar bort filtrering av inmatning till basem
	list("PI##1");	Patchar in filtrering av inmatning till basen
	list("PO##0");	Patchar bort filtrering av utmatning frn basen
	list("PO##1");	Patchar in filtrering av utmatning frn basen
	
Om inget av de fyra kommandona PF, P8, PI eller PO ges med argument 1, s fr
Michtron inte ngra nya egenskaper, d dessa r avstngda vid uppstart.
Enda skillnaden mot att kra utan MTx4 r d den adopterade systemfonten.

Jag rekommenderar dessutom att PF, den enda patch som r aktiv vid uppstart,
aldrig tas bort, eftersom sysop d inte kan se 8bits koder.
Obs, att PF inte tillter 8bits koder i ngon annan hantering n display
(lokalt p konsollen allts).  Vill man ha mer s krvs ven patch P8.

Aktivering av filtren fr heller ingen mrkbar effekt, frrn man frndrar
versttnings-tabellerna, som ju r initierade att verstta utan ndringar.

Kommandona fr detta r Ix och Ox fr inmatning respektive utmatning, dr
'x' representerar den karaktr som ska versttas, medan argumentet ska vara
det tecken man vill verstta till.

Dessutom kan filter-tabellerna rensas till original-lget med kommandona
CI respektive CO, vars argument fr nrvarande ignoreras men SKA vara '0'.
Det senare fr att garantera kompatibilitet med framtida versioner av MTx4.

Om jag exempelvis har en ren Ataribas och vill serva anvndarna med svenska
tecken p in och utmatning, och nd lagra dem som 'msvingar' i brev etc,
s att brevutbyte blir mjligt med andra baser, d gr jag fljande:

	list("CI##0");
	list("CO##0");

Dessa tv rader rensar filtertabellerna (behvs om de varit i bruk tidigare).

	list("I##]");
	list("I##[");
	list("I##\");
	list("I##}");
	list("I##{");
	list("I##|");
	list("PI##1");
	
Dessa sex rader laddar versttnings-tabellen fr inmatning, medan den
sjunde aktiverar filtreringen.  Drefter anlnder anvndarens svenska 8-bits
koder som "msvingar" i basen.  Nu gr vi tvrtom t andra hllet:

	list("O]##");
	list("O[##");
	list("O\##");
	list("O}##");
	list("O{##");
	list("O|##");
	list("PO##1");

Detta medfr allts att de "msvingar" basen har inte skickas till anvndarna
utan att frst omvandlas till 8-bitars svenska tecken.
(iofs inte helt komplett, men det r ju ltt att lga till , , , .)

Hr leder allts versttningen till att basen internt blir kompatibel med de
baser som krver att 7-bits standard efterlevs, trots att kommunikationen med
anvndarna sker enligt 8-bits standard, men man kan gra helt tvrsom ocks.

Gr man som ovan, s behver man inte ocks aktivera 8-bits mode, eftersom
de aktuella 8-bits koderna bara frekommer p "utsidan" av filtren, och
allts aldrig ska n sjlva bbs-hanteringen.

Lmnar man 8-bits mode frnslaget, s blockeras alla 8bits koder utom de som
genom filtrering fr en 7-bits representant p "insidan".

Har man dremot den motsatta filtreringen, eller nd vill tillta alla 8bits
koder i basen s mste 8bits mode aktiveras.  Om man d vill blockera enstaka
tecken s kan det gras genom att filtret verstter den till en Control-kod
som saknar implementering (till exempel Control-A, skrivs som "\1" i MCL).
Observera att ocks tecken som saknar tangenter kan stllas in med hjlp av
MCL's strng-macron.

Fr att ex.vis sprra ascii-kod 247 s kan vi nyttja:

	list("I\247##\1");

Vill man ha 8bits mode frnslaget s kr man:

	list("P8##0");

annars slr man p 8bits mode med:

	list("P8##1");

Nr man vl definierat sina filter s kan dessa enkelt kopplas av och p,
utan att man behver fylla om tabellerna, som visas hr:

	list("PI##0");
	list("PO##0");
	list("P8##0");
	
Dessa tre rader stnger av filtreringen utan att rucka tabellerna, och fr
ocks tillbaks Michtron till ren 7-bits hantering (sista raden).
Vill man sedan sl p allt igen, s rcker 3 rader till det ocks:

	list("PI##1");
	list("PO##1");
	list("P8##1");

Jag ska vl ocks tillgga att sjlva kommandona kan ges godtyckligt som sm
eller stora bokstver, medan dremot tabellindex och argument, givetvis ska
ha sina exakta tecken.

Det betyder allts att:

	list("pi##0");  r samma sak som  list("PI##0");

men att:

	list("ia##A");  r motsatsen till  list("iA##a");

I foldern 'MCL\', som jag inkluderat i arkivet, finns ovanstende rutiner
samt ngra andra, i lmpliga moduler att anropas frn 'MAIN.MCL'.
Dr finns de i svl kllkods-format som i form av frdiga MCL-filer.
Det kan ofta vara lmpligt att i stllet kopiera rutinerna till subrutiner
i BBS'ens MAIN.M och kompilera fram en ny MAIN.MCL .
Detta gr ju att man kan anropa dem utan ondiga filaccesser.

Jag har ocks inkluderat assembler-kllkoden fr MTx4, s att intresserade
kan studera hur det gjorts.  Dremot kan den inte direkt omassembleras, d
jag av utrymmesskl finner det olmpligt att ta med alla "include"-filer.

-----------------------------------------------------------------------------

Mvh:  Ronald Andersson

-----------------------------------------------------------------------------
End of file:	MT_X.DOC