* simser * STX/SRX-Erweiterung fr den Sinclair QL * .hpr * 20.2.1997 *
H.-Peter Recktenwald, Tel: +49 30 8520413, email: phpr@berlin.snafu.de

Frei zur beliebigen Verwendung und Weitergabe, sofern dies kostenlos
geschieht und Code wie Text, bei eigener Bearbeitung ggf. zustzlich,
unverndert und kostenlos mitgegeben werden.

        SIMple SER-Erweiterung, vorlufige Spezifikation:

SIMSER ist eine einfache SER-Ergnzung um fr denselben SER-Anschlu
gleichzeitig verwendbare getrennte Kanle fr Sendung und Empfang.

Sie dient auerdem im QL dem sicheren Umgang mit den Schnittstellen bei
Nutzung desselben QDOS-Kanals aus verschiedenen Jobs, wo es sonst u.U.
zu unlsbarer gegenseitiger Verriegelung kommen kann. Weiter soll sie
Compatibilitt zwischen dem Schwarzen QL (sowie dem SMSQ der QXL) und
SMSQ/E schaffen helfen.

Von den Sonderheiten der SMSQ/E-Definition wird die Mglichkeit der fr
auswhlbare Kanle vom aktuellen TRA-Zustand unabhngigen Freigabe der
Zeichenumsetzung auch im QL untersttzt. Diese ergnzt um einzelnen
Kanlen einprgbare eigene Umsetzungstabellen, wodurch sie vom Zustand
der Systemeinstellung restlos unabhngig werden (vorlufig nur ab JS).
Bei MINERVA ergeben sich dann durch die dort auch noch vectorisierten
Bearbeitungsroutinen alle wie auch immer gearteten Mglichkeiten der
Verarbeitung smtlicher Datencodierungs- und bertragungsprotokolle.

Daneben reduziert sich die Gesamtbelastung des QL-Systems, wenn eine
Schnittstelle nur zum Senden benutzt wird. Je nach Situation besonders
auffllig u.U. beim Datenaustausch (direkt, Modem, etc.) ber die eine
und nur der Ausgabe (z.B. zum Drucker) ber die andere Schnittstelle.


Installation:

"SIMSER_BYT" kann mit LRESPR in jedes QDOS-artige System geladen werden.
Das Device wird nur installiert, wenn es im System noch unbekannt ist,
und der Aufruf aus dem Stamm-Basic (Job 0) erfolgt.
Der Code kann darum ohne Beachtung der Situation jederzeit und mehrfach
aufgerufen werden, ohne da dies schdliche Wirkungen hervorrufen wrde.

Aus Grnden der Programm-bertragbarkeit installiert sich das Device im
SMSQ/E ebenfalls. Wie im QL bleibt die zugrundeliegende Gertedefinition
unverndert, insbes. die erweiterte Funktionalitt bleibt also erhalten.
Einzig die zustzliche zwangsweise Pufferung jeden einzelen Kanals wird
fr die Ports 1 und 2 unterbunden. Sie hat sich nicht nur als von Fehlern
durchsetzt, sondern oft auch als als auerordentliches Hindernis erwiesen.
Wer aber gerade darauf Wert legt, ldt die Erweiterung nicht!
Zustzlich wird die berlagernde Kanaltabelle verwaltet, und es gelten
die u.a. Sonderoperationen (z.B. Seitenvorschub beim Basic-Kommando CLS).

Der Code wurde erprobt im Schwarzen QL mit Minerva 1.93 und GC sowie SGC
und im QXL-System mit SMSQ 2.76 und SMSQ/E 2.79.
Auerdem im Atari-Mega-ST mit E.32-Software und SMSQ/E 2.79.

Zur Prfung auf Vorhandensein der QL-Hardware bei intaktem Co-Protz dient
der IPC-Befehl 15 mit Datenbyte $5A. Kooperation mit HERMES ist ungeklrt.


Zur Gerte- und Kanaldefinition:

Allgemeine Zulssigkeit von Portnummern wird nicht gesondert berprft.
Ab Port 3 wird die Hilfsdefinition nur passiv eingerichtet, Bearbeitung
erfolgt einzig durch die entspr. Systemroutinen.
Das folgende gilt ausschlielich fr die SER1- und SER2-Schnittstellen.

Allen Kanaltypen gemeinsam ist die zustzliche Kontrolle, ob bei einem
bestimmten Kanal eine Ein- oder Ausgabe-Operation bereits im Gange ist:

Da es bei gleichzeitiger Verwendung desselben Kanals aus mehreren Jobs
im QL auch bei begrenzter Wartezeit zu einer Art Verhaken kommen kann,
soda die beteiligten Aufrufe nicht mehr aus ihren Trap#3-Operationen
zurckkehren, wird in solchen Fllen der Fehlercode -1, err.nc, zurck-
gegeben. Dadurch ist dafr gesorgt, da der Aufruf bei entsprechender
Angabe in D3 bis zum Abschlu der gerade aktiven Operation wartet.

Die zugehrigen Puffer des jeweiligen Systems lassen sich durch Aufruf
der QDOS-Trap fs.trunc (TRUNCATE im Basic) aus einem STX-Kanal lschen.
Die QL-Hardware der benutzten Schnittstellen wird ggf. neu geffnet.


Kanaltypen:

Alle OPEN-Parameter wie im QL, zustzlich auch D oder T (s.u.).
Die weiteren SMSQ/E-spezifischen Optionen werden ohne Aktion fehlerfrei
angenommen, aber nur im SMSQ/E werden sie entsprechend auch bearbeitet.

Die QDOS-Operationen io.pend und sd.extop sind fr jeden der Kanaltypen
zugelassen, Op-Code 8 nur fr STX- und SRX-Kanle.

SER     wird unverndert behandelt.

SRX und STX
        Alle Parameter aus QL oder SMSQ/E sind zulssig. Die ber die QL-
        Definition hinausgehenden Angaben X, A und F bleiben unbearbeitet
        und ohne Fehleraktion.
        Damit soll die Arbeit ber Netz erleichtert und die Verwendung von
        Programmen in unterschiedlichen Systemen vereinfacht werden.

        Die zwangsweise zustzliche kanalbezogene Pufferung fr Sendekanle
        ist halbherzig und so weit an der Wirklichkeit vorbeiprogrammiert,
        da sie den geordneten Umgang mit den Schnittstellen stark behindert.
        Darum wird diese Pufferung fr die STX- und SRX-Kanle unterbunden.
        Im SMSQ/E steht dann wie in den anderen Systemen je Port und Richtung
        ein Puffer in Gestalt einer Queue von Standardlnge zur Verfgung,
        dort also mit der ggf. durch SER_BUFF eingestellten Lnge.

        Einzig die gezielt schaltbare Zeichenumsetzung hat groe Vorteile:
        Die SMSQ/E-Optionen D und T werden dadurch behandelt, da fr jede
        einzelne Ein-/Ausgabe-Operation beim Kanaltyp "T" die TRA-Funktion
        freigegeben und beim Typen "D" gesperrt wird. Auf diese Weise wird
        erreicht, da sich die Ausfhrung durch die berlagernde Definition
        zeitlich nur um die Zustandsabfrage und -Wiederherstellung verzgert.
        Es ist aber erforderlich, da wenigstens einmal der Basic-Befehl TRA
        (oder die entsprechende QDOS-Trap) mit einem Parameter =/= 0 aufge-
        rufen wurde, um die Systemtabelle zur Zeichenumsetzung berhaupt
        zu besetzen.

        Ergnzend zur einfachen Funktionalitt aus dem SMSQ/E wird hier den
        Kanlen mit T-Option die Tabelle selbst eingeprgt, soda auch nach
        Umstellen des Systems auf eine andere Codierung bestehende Kanle
        unverndert weiter mit derselben Tabelle arbeiten. Erst beim ffnen
        eines neuen Kanals (oder nach bergabe an den Kanal mit <sd.fount>,
        s.u., QDOS-Traps) gilt fr diesen dann die neue Tabelle.

        Die im QDOS nicht definierten Codes 6 und 8 sind freigegeben, um sie
        fr andere SER-Erweiterungen verfgbar zu halten. Sie werden je nach
        Situation durch den systemeigenen Handler ggf. mit err.bp abgewiesen.

SRX     weist Sendeoperationen mit D0:=-15 (err.bp) ab.

STX     weist Empfangsoperationen mit D0:=-15 (err.bp) ab.
        Zustzlich gilt IOB.SUML, Code 6, zur Ausfhrung der Trap IO.SSTRG,
        Code 7, bei hierfr vorbergehend stillgelegter Zeichenumsetzung.
        IO.PEND, Code 0, kommt mit err.nc (-1) zurck, wenn der Kanal durch
        eine andere Operation zeitweilig gesperrt ist, sonst err.bp (-15),
        da die Trap ansich nur fr den Empfnger vorgesehen ist. Weiter:

        Opcode  Name     Aktion
        17      sd.tab   <tab>  sendet ein Byte  9
        18      sd.nl    <cr>                   10
        19      sd.pcol  <bs>                    8
        20      sd.ncol  <bl>                   32
        22      sd.nrow  <lf>                   13
        32      sd.clear <ff>                   12      Basic: CLS
        33      sd.clrtp <ff>                   12             CLS 1
        34      sd.clrbt <ff>                   12             CLS 2

        Zum Umstellen der kanaleigenen Zeichenumsetzung:
        37      sd.fount mit A1 = A2 als Ptr auf (neue) TRA-Tabelle;
                A1 = A2 als Schutzmanahme bei versehentlichem Aufruf
                mit fr einen CON-/SCR-Kanal vorgesehenen Parametern.

        IPC-Reset und Leeren von Empfangs- und Sendepuffer sind oftmals
        ntzlich, wenn die Daten verzgert oder offenkundig verdorben
        empfangen werden, oder die Sendungen ins Stocken geraten. Dazu:

        75      fs.trunc mit D1 = D2 = -1

        Beim Aufruf dieser Trap aus einem Kanal zum Port 1 oder 2 wird
        im QL der IPC zurckgesetzt und soweit erforderlich werden die
        entspr. Schnittstellen wieder geffnet.
        Auerdem lscht der Aufruf alle Puffer dieser beiden Ports.

        Dazu werden die IPC-Aufrufe zum Reset (reset.cmd, Op. 0) und,
        wenn dieser ohne Fehlercode quittiert wurde, zum ffnen der
        Empfngerseite ops1.cmd und ops2.cmd (Op. 4 und 5) benutzt.
        Die Sendeseite wird nicht gesondert behandelt, da sie mit der
        Installation des Systempuffers freigegeben ist, und nur aktiv,
        wenn dort Daten zur bertragung vorhanden sind.

SD.EXTOP-Aufrufe:

Frei definierte Operationen knnen mit sd.extop (D0=9) an allen Kanaltypen
der Ports 1 und 2 ausgefhrt werden. Das ist zugleich eine Mglichkeit,
diese Gertedefinition von anderen Varianten eindeutig zu unterscheiden.

Im Aufruf steht folgende Registerbelegung zur Verfgung:

D0      Op-Code (9)
D4.B    Kanaltyp -2:STX -1:SER 1:SRX
D5.B    alter TRA-Zustand
D7.W    -1:Port 1, 0:Port 2
A0      cdt des Systemkanals
A2      berlagernde Secundr-cdt
A3      Handler-Basisadresse des Systemkanals
A4      die mit A2 in die Trap bergebene Aufrufadresse
A5      Handler-Basisadresse der Secundrdefinition

Alle Register sind frei verwendbar, keines mu restauriert werden.
A0 und A3 werden abschlieend vom Handler richtig besetzt.

D0      Der Fehlercode darf nicht in Konflikt mit Programmen geraten,
        wo diese Trap der Erkennung bestimmter Kanaltypen (CON etc.)
        dient. Darum setzt ihn der Handler auf err.bp (-15), wenn nicht
        schon im Trap-Aufruf selbst ein negativer Wert angegeben wurde.
        Als Erfolgskontrolle bietet sich etwa die Rckgabe von err.nj (-2)
        an, welcher Code in i/o-Traps nur bei iop.pick aus dem Pointer-I.F.
        vorkommen kann und darum Mideutungen ausschliet.

Sollte eine andere SER-/SRX-/STX-Definition die sd.extop-Trap ebenfalls
zulassen, hilft bei der sicheren Erkennung die Marke "SRT%" auf -36(A3).

Folgende Parameter der Devicedefinition und der Kanaltabellen werden
insbes. bei eigenen Handler-Routinen in sd.extop-Aufrufen ntzlich sein:

Handlerdaten (in sd.extop auf A5 bezogen):

psgnm   -36      .l signatur "SRT%"
pqlfl   -24      .b flag 0 bei QL-hardware mit intaktem IPC
psqfl   -20      .b flag -1 bei SMSQ/E, 1 bei SMSQ, sonst 0
pohnd   -16      .l basisadresse des systemeigenen devicehandlers
poio    -12      .l systemeigener i/o-einsprung
poopn    -8      .l open dto.
poclo    -4      .l close dto.
* ab 0 zhlend je portnummer ein datenposten:
psctyp   48      .b flags -2:empfnger 0:ohne kanal 1:sender -1:bi-direktional
ptxfl    56      .b STX-zugriffsflags bit 7 gesetzt bei kanalsperrung
prxfl    64      .b SRX, dto.
psefl    72      .b SER, dto.
prque   120      .l ptr auf systemeigene empfangsqueue-header (8 langworte)
psque   152      .l ptr auf systemeigene sendequeue-header (8 langworte)
ptabl   256     - vorlufiges(!) tabellenende (312 bytes insgesamt) -

HINWEIS: <pr/sque> im SMSQ/E bei SER-Kanlen oder Portnummern ber 2 wertlos.

Daten der Kanaltabellen (in sd.extop auf A2 bezogen):

* die ersten neun posten werden aus der decodierung des kanalnamen besetzt
csport  24 port  .w nummer 1..8, vorgabe 1
cspar   26 OEMS  .w parity-code  ohne:0 O:2 E:4 M:6 S:8 -> 7bit-typ bei >0
cshs    28 IHX   .w sende-handshake  ohne:0 I:1 H:2 (X:3 nicht ausgwertet)
cstra   30 DT    .w TRA ohne D:0 mit T:1 vorgabe:TRA nach aktuellem zustand
csprot  32 RCA   .w protokoll  ohne:0 R:1 C:2   (A:3 nicht ausgewertet)
csfz    34 FZ    .w dateiende-codierung         (F:1 nicht ausgewertet)
csxcdt  36 zahl  .w 1/8 cdt-verlngerung
csbff   38 zahl  .w                             (nicht ausgewertet)
cstyp   40 typ   .b bewerteter kanaltyp -2:srx -1:ser 1:stx
;       41       .b typ aus dem kanalnamen 1:SER 2:SRX 3:STX
csttb   46       .l 0 oder adresse der TRA-tabelle bei OPEN des kanals
cscdt   50       .l cdt des systemkanals
csrq    62       .l ptr auf sende-/empfangsqueue-header, 0 bei SER
cscdtl  84      - lnge der cdt - anfang der optionalen verlngerung -

HINWEIS: Hier nicht benannte Posten sind internen Zwecken vorbehalten
oder werden in der erweiterten Version benutzt. Sie sind _nicht_ frei.
Fr eigene kanalbezogene Daten steht die cdt-Verlngerung zur Verfgung.
Zu Eintragungen dorthin wird Verwendung der sd.extop-Trap empfohlen.


Intern:

Das Device berlagert die systemeigene SER-Definition einschlielich
eventuell existierender Varianten wie STX und SRX der E-Software. Es
verwendet in jedem Falle aber nur die mit SER bezeichneten Kanaltypen
und die Parameter(gruppen) OEMS, IH, DT, RC und Z, von denen D und T
und die Zahl zur cdt-Verlngerung in der Hilfsdefinition verarbeitet
werden, nicht aber an den Kanal des Betriebssystems durchgereicht.
Alle zustzlich in den Systemen mit Atari-/SMSQ-E-Software erlaubten
Parameter bleiben unbeachtet.

Wenn zum betr. Port noch kein Kanal der anderen Richtung existiert,
wird zunchst ein SER-Kanal der Systemdefinition geffnet. Wird die
Empfngerseite nicht gebraucht, schliet der Aufruf den zugehrigen
IPC-Port. Wird der Sender nicht gebraucht, markiert er die Sendequeue
<eof>. Existiert schon ein Sender und wird der Empfnger angefordert,
ffnet er dessen IPC-Seite und bernimmt die bestehende systemeigene
Grunddefinition. Letzteres gilt auch fr das Einrichten eines Senders
bei bestehendem Empfnger, zustzlich wird dann nur die <eof>-Marke
der Sendequeue gelscht.

Die berlagernde Definition legt somit keine richtungsbezogenen Kanle
an. Ihre Funktion besteht darin, die Aufrufe selbst richtungsbezogen
zu bewerten und sie ggf. an den Systemkanal weiterzuleiten.

Die magebliche Adresse der jeweils vom System benutzten Queue steht in
den Variablen der Hilfsdefinition der SER-/SRX-/STX-Kanle. Sie kann so
immer zuverlssig und ohne Rcksicht auf das jeweilige Betriebssystem
fr eigene Handleroperationen den Kanalvariablen entnommen und benutzt
werden. Voraussetzung ist die bislang stets eingehaltene Lage der SER-
Queue-Adressen des Betriebssystems an den untengenannten Positionen -
verbunden mit der Hoffnung, da nicht hierdurch veranlat der Groe
Unfehlbare, Schpfer zahlloser SMSQ-Varianten, das nun ndern wird:

                                        QL                   SQ
Header der Empfnger-Queue auf       32(cdt)            (40(cdt))+16
           Sender               ((32(cdt)+12)+1)&-2     (44(cdt))+16

Dabei zu beachten, da die beim Standard-QL resultierende Position der
Sender-Queue auf 130(cdt), und damit die Lnge der Empfnger-Queue, nicht
verndert werden darf, weil es je nach Rom Stellen im Original-Code gibt,
wo die Zahl 130 fest verankert ist.


Fr weitere Ausknfte bitte email an o.g. Adresse.

 .hpr'97  eof 
