home *** CD-ROM | disk | FTP | other *** search
/ AMIGA PD 1 / AMIGA-PD-1.iso / Programme_zum_Heft / Anwendungen / Kurztests / TheAnswer / Libs / MetaXPR.dok next >
Text File  |  1993-03-14  |  34KB  |  668 lines
  1. ========================== metaxpr.library 4.0 ============================
  2. ===========================================================================
  3. Eine  Bibliothek,  die  Datentransfer  über xpr#?.library-Implementierungen
  4. erleichtert.  © Copyright 1991-92 by Olaf Barthel, alle Rechte vorbehalten.
  5.    Es   wird   keinerlei   Gewährleistungspflicht   für   die  vollständige
  6. Funktionsfähigkeit   der   in   diesem   Dokument   beschriebenen  Software
  7. übernommen.  Jegliche Nutzung geschieht auf eigene Gefahr.
  8.  
  9.  
  10. =============================== Motivation ================================
  11. ===========================================================================
  12. Fast   alle   Programmierer,   die   sich  mit  der  Erstellung  von  Tele-
  13. kommunikationsoftware  beschäftigen,  stolpern  irgendwann  einmal über die
  14. xpr#?.libraries,  die  auf allgemeine Art und Weise Protokollle für Up- und
  15. Download implementieren.
  16.    An  dieser  Stelle  verläßt  die meisten Programmierer der Mut.  Wer hat
  17. schon  Lust,  eine  über  100 KBytes große Dokumentation (in Englisch!  wer
  18. spricht  schon  Englisch!)  durchzuarbeiten,  um  hinterher  doch nur einen
  19. Absturz zu Gesicht zu bekommen.
  20.    Nun  gibt  es  aber  dennoch Programmierer, die es geschafft haben, eine
  21. Implementierung  der  entsprechenden  Transferroutinen  zu  schreiben.  Das
  22. Resultat  sind  Programme,  die mit einem Satz Parameter von CLI oder Shell
  23. aufgerufen werden können.
  24.    Hier  liegt  der  Hund  begraben, denn soweit die Implementierung stabil
  25. ist,  so  ergeben  sich  beim  Aufruf Probleme:  Ist der Transfer geglückt?
  26. Wurde   das   Programm   eventuell   gar  nicht  geladen?   Wie  sehen  die
  27. Einstellungen des serial.device aus?
  28.    Hinzu   kommt   meist   noch,   daß   ein   Programm,  das  ein  solches
  29. Transferprogramm  aufrufen  will,  unbedingt  von CLI oder Shell aufgerufen
  30. werden muß.
  31.  
  32.    Vor  diesem  Hintergrund  habe ich mich entschlossen, eine Bibliothek zu
  33. schreiben,   die   externe   Programmaufrufe  für  die  Durchführung  eines
  34. Up-/Downloads  überflüssig  macht.   Weiterhin  hat das aufrufende Programm
  35. fast völlige Kontrolle über die Ansteuerung der seriellen Schnittstelle und
  36. die Möglichkeiten des Up-/Downloads.
  37.  
  38.  
  39. ==================== Bestandteile des MetaXPR-Paketes =====================
  40. ===========================================================================
  41. Die   folgenden  Dateien,  bzw.   Verzeichnisse  samt  Inhalt  gehören  zum
  42. MetaXPR-Paket:
  43.  
  44.    MetaXPR.dok..................... Die Dokumentation der Library
  45.  
  46.    metaxpr.library................. Die  Library  selbst  (auf allen  680x0
  47.                                     Prozessoren lauffähig)
  48.    metaxpr.library.020............. Die Library selbst (benötigt mindestens
  49.                                     einen  68020  Prozessor).  Um   sie  zu
  50.                                     installieren,   bitte   umbenennen   in
  51.                                     "metaxpr.library"
  52.    metaxpr_lib.fd.................. Funktionsdefinitionsdatei der Library
  53.  
  54.    MetaXPR.h....................... Header-Datei für `C' Programmierer
  55.  
  56.    Receive,Receive.c............... Beispielprogramm für das Empfangen  von
  57.                                     Dateien, in `C' geschrieben
  58.  
  59.    Send,Send.c..................... Beispielprogramm  für  das  Verschicken
  60.                                     von Dateien, in `C' geschrieben
  61.  
  62.    SendFiles,SendFiles.c........... Beispielprogramm  für  das  Verschicken
  63.                                     von mehreren Dateien,in `C' geschrieben
  64.  
  65.    LinkLibs/amigados_metaxpr.lib... Linker-Library im AmigaDOS-Objektformat
  66.    LinkLibs/manx36_metaxpr.lib..... Linker-Library für Aztec `C' 3.6
  67.    LinkLibs/manx50_metaxpr.lib..... Linker-Library für Aztec `C' 5.0
  68.    LinkLibs/sasc_metaxpr.lib....... Linker-Library für Lattice/SAS `C'
  69.  
  70.    Glue,SAS_Glue................... Quellcode zu den Linker-Libraries
  71.  
  72. ============================= Funktionsweise ==============================
  73. ===========================================================================
  74. Die Bibliothek metaxpr.library ist eine gewöhnliche Amiga-Systembibliothek,
  75. die  in  das LIBS:-Verzeichnis kopiert werden sollte.  Sie benimmt sich wie
  76. jede  andere  Bibliothek  (intuition.library, graphics.library, etc.).  Wer
  77. sich  mit  diesen  Bibliotheken abgerackert hat, der wird auch diese nutzen
  78. können.
  79.  
  80.    Nach   dem   Öffnen  der  Bibliothek  stehen  dem  Programmierer  sieben
  81. Funktionen zur Verfügung:
  82.  
  83.    TransferSetup......... Initialisiert  den  seriellen  Treiber und öffnet
  84.                           die  benötigte  xpr.library.   Diese  Routine muß
  85.                           aufgerufen   werden,  bevor  eine  der  folgenden
  86.                           Steuerroutinen aufgerufen wird.
  87.  
  88.    TransferSetupShared... Eine  in  Version  2.0 der Bibliothek eingeführte
  89.                           Funktion, die analog zu TransferSetup() arbeitet,
  90.                           es aber erlaubt, vom aufrufenden Programm bereits
  91.                           für   den   Datentransfer   geöffnete  Kanäle  zu
  92.                           verwenden,   anstatt  diese  von  der  Bibliothek
  93.                           öffnen zu lassen.
  94.  
  95.    InstallTransferNote... Diese   Funktion   wurde   in   Version  3.0  der
  96.                           Bibliothek   eingeführt   und   erlaubt  es,  den
  97.                           Transferroutinen  eine  Struktur zu übergeben, in
  98.                           der  Transferparameter  (wie  z.B.   verbleibende
  99.                           Übertragungsdauer   in   Sekunden   und  noch  zu
  100.                           übertragende Bytes) vermerkt werden und, wenn ein
  101.                           Struktureintrag   auf   0   gesetzt   wird,   den
  102.                           programmtechnischen    Abbruch    des   Transfers
  103.                           herbeiführt.
  104.  
  105.    ReceiveFile........... Empfängt  eine  Datei  unter Ausnutzung der durch
  106.                           TransferSetup/TransferSetupShared   eingestellten
  107.                           Parameter.
  108.  
  109.    SendFile.............. Verschickt  eine Datei unter Ausnutzung der durch
  110.                           TransferSetup/TransferSetupShared   eingestellten
  111.                           Parameter.
  112.  
  113.    SendMultipleFiles..... Diese   Funktion   wurde   in   Version  3.1  der
  114.                           Bibliothek  eingeführt  und dient zum Verschicken
  115.                           mehrerer Dateien am Stück.  Es werden wie bei der
  116.                           Funktion         `SendFile'        die        mit
  117.                           TransferSetup/TransferSetupShared   eingestellten
  118.                           Parameter benutzt.
  119.  
  120.    GetOptions............ Liest  die  für die aktuell geöffnete xpr.library
  121.                           eingestellten Parameter aus.
  122.  
  123.    SetOptions............ Setzt   die   internen   Parameter   der  aktuell
  124.                           geöffneten   xpr.library   (siehe   dazugehöriger
  125.                           Dokumentation).
  126.  
  127.    Im  folgenden  wird  auf  die  einzelnen  Routinen  und  deren Benutzung
  128. eingegangen:
  129.  
  130.                                      *
  131.  
  132. Fehler = TransferSetup(Treiber, Unit, Bibliothek, Baudrate, Datenbits,
  133.   D0                      A0     D0       A1        D1         D2
  134.  
  135.                        Stopbits, Parität, Handshaking)
  136.                           D3        D4        D5
  137.  
  138. Treiber         - Name    des    zu    benutzenden    seriellen    Treibers
  139.                   (serial.device, modem0.device, etc).  Wird als eine durch
  140.                   ein Nullbyte abgeschlossene Zeichenkette übergeben.
  141.  
  142. Unit            - Die   Treibereinheit,   die   angesprochen  werden  soll;
  143.                   entspricht  üblicherweise der Nummer des seriellen Ports,
  144.                   sollte  man  über keine Steckkarte mit mehreren seriellen
  145.                   Anschlüssen verfügen, so ist hier eine 0 einzutragen.
  146.  
  147. Bibliothek      - Der  Name  der  xpr.library, die für den Transfer benutzt
  148.                   werden  soll (xprzmodem.library, xprxmodem.library, etc).
  149.                   Der  Name  wird  als  durch  ein  Nullbyte abgeschlossene
  150.                   Zeichenkette übergeben.
  151.  
  152. Baurate         - Übertragungsgeschwindigkeit    in   Bits   pro   Sekunde.
  153.                   Gebräuchliche  Baudraten  bewegen  sich  zwischen 300 und
  154.                   31250 Baud.
  155.  
  156. Datenbits       - Die  Anzahl  Datenbits, die bei der Übertragung verwendet
  157.                   werden sollen.  Üblicherweise 8, manchmal auch 7.
  158.  
  159. Stopbits        - Die  Anzahl  Stopbits,  die bei der Übertragung verwendet
  160.                   werden sollen.  Üblicherweise 1, sonst auch 0 oder 2.
  161.  
  162. Parität         - Die  bei  der Übertragung zu verwendende Parität, gültige
  163.                   Werte sind:
  164.  
  165.                   0 - Keine Parität.
  166.                   1 - Gerade Parität.
  167.                   2 - Ungerade Partität.
  168.                   3 - Paritätsbit ist immer gesetzt.
  169.                   4 - Paritätsbit ist immer gelöscht.
  170.  
  171. Handshaking     - Gibt  an,  ob  Hardware-Handshaking  eingeschaltet werden
  172.                   soll (0 = aus, 1 = ein).
  173.  
  174.    Es  muß  darauf  hingewiesen  werden,  daß  diese  Routine den seriellen
  175. Treiber  exklusiv für sich öffnet.  Hat das aufrufende Programm den Treiber
  176. bereits  für  sich  belegt,  wird  der Aufruf dieser Funktion fehlschlagen!
  177. Wenn  man  diesen  Effekt vermeiden möchte, sollte man statt dieser Routine
  178. besser TransferSetupShared() verwenden.
  179.  
  180.    Der  von  dieser  Routine  geöffnete serielle Treiber wird erst nach dem
  181. Schließen der metaxpr.library freigegeben!
  182.  
  183.    Diese  Routine  liefert  einen  Wert  zurück, der gleich 0 ist, wenn die
  184. Initialisierungen  geglückt  sind  und ungleich 0, wenn die Initialisierung
  185. fehlgeschlagen   ist.    Anhand  des  zurückgelieferten  Wertes  läßt  sich
  186. entscheiden, welcher Fehler aufgetreten ist:
  187.  
  188.    1 - Einer oder mehrere an die Routine übergebenen Aufrufparameter waren
  189.        nicht zulässig.
  190.  
  191.    2 - Es konnte nicht genügend Speicher angefordert werden.
  192.  
  193.    3 - Beim Anlegen von MsgPorts ist ein Fehler aufgetreten (alle
  194.        Signalbits sind offenbar schon belegt).
  195.  
  196.    4 - Beim Öffnen des seriellen Treibers ist ein Fehler aufgetreten.
  197.  
  198.    5 - Die Parameter des seriellen Treibers ließen sich nicht setzen.
  199.  
  200.    6 - Der Zeitgeber (timer.device) ließ sich nicht öffnen.
  201.  
  202.    7 - Die zu verwendende xpr.library ließ sich nicht öffnen.
  203.  
  204.    8 - Die Initialisierung der xpr.library schlug fehl.
  205.  
  206.    9 - Wurden  die  Übertragungsparameter  über TransferSetup() gesetzt, so
  207.        können  sie  nur  über die selbe Routine verändert werden.  Gleiches
  208.        gilt für die Routine TransferSetupShared().
  209.  
  210.    Diese  Routine  selbst  läßt  sich  beliebig  oft  mit  neuen Parametern
  211. aufrufen.   Alle  hier  angeforderten  Resourcen  werden beim Schließen der
  212. Bibliothek wieder freigegeben.
  213.  
  214.                                      *
  215.  
  216. Fehler = TransferSetupShared(ReadRequest, WriteRequest, Bibliothek)
  217.   D0                             A0            A1           A2
  218.  
  219. ReadRequest     - Die  vom  aufrufenden  Programm  zum  Lesen von Daten der
  220.                   seriellen   Schnittstelle   verwendete  Struktur  (struct
  221.                   IOExtSer).
  222.  
  223. WriteRequest    - Die  vom  aufrufenden Programm zum Schicken von Daten zur
  224.                   seriellen   Schnittstelle   verwendete  Struktur  (struct
  225.                   IOExtSer).
  226.  
  227. Bibliothek      - Der  Name  der  xpr.library, die für den Transfer benutzt
  228.                   werden  soll (xprzmodem.library, xprxmodem.library, etc).
  229.                   Der  Name  wird  als  durch  ein  Nullbyte abgeschlossene
  230.                   Zeichenkette übergeben.
  231.  
  232.    Ein  Telekommunikationsprogramm  sollte  üblicherweise  mindestens  zwei
  233. Kanäle offen haben, um auf die seriellen Schnittstelle zugreifen zu können.
  234. Möchte man diese Kanäle nicht schließen (einige Modems legen z.B.  auf wenn
  235. die  vom serial.device aktivierte DTR-Leitung plötzlich abfällt), so bietet
  236. es  sich  an,  sie  dieser  Routine  zu  übergeben.  Vorsicht:  die Routine
  237. überprüft, ob ReadRequest und WriteRequest verschieden sind und liefert bei
  238. Übereinstimmung Fehlercode 1 zurück.
  239.    TransferSetupShared() verhält sich ansonsten genauso wie TransferSetup()
  240. und liefert dieselben Fehlercodes zurück.
  241.    Baudrate  oder  Parameter  von ReadRequest und WriteRequest werden nicht
  242. modifiziert.   Ich  empfehle  sowohl  vor  dem  Aufruf  dieser  Routine ein
  243. CMD_CLEAR an den seriellen Treiber zu schicken, als auch nach dem Schließen
  244. der   metaxpr.library.    Es  sollten  keine  Annahmen  über  die  Einträge
  245. io_Command,   io_Data,   io_Actual   oder  io_Length  von  ReadRequest  und
  246. WriteRequest gemacht werden, wenn die Routinen SendFile() und ReceiveFile()
  247. zurückkehren!
  248.  
  249.                                      *
  250.  
  251. Erfolg = ReceiveFile(Name, ÖffneFenster, Bildschirm)
  252.   D0                  A0       D0            A1
  253.  
  254.  
  255. Name            - Der  Name  der  zu empfangenden Datei.  Der Name wird als
  256.                   eine   durch  ein  Nullbyte  abgeschlossene  Zeichenkette
  257.                   übergeben.   In diese Zeichenkette wird auch der Name der
  258.                   zuletzt  übertragenen Datei eingetragen, die Zeichenkette
  259.                   sollte mindestens 256 Zeichen lang sein.
  260.                      Nach  Abschluß  der  Übertragung  befindet sich in der
  261.                   übergebenen   Zeichenkette   der   komplette   Name   der
  262.                   empfangenen  Datei  (der  sich  besonders  bei Kermit und
  263.                   ZModem  vom  übergebenen  Dateinamen unterscheiden wird).
  264.                   Die   dieser   Routine   übergebene  Zeichenkette  sollte
  265.                   mindestens 256 Zeichen lang sein.  Wurden mehrere Dateien
  266.                   empfangen,  so  enthält  diese Zeichenkette nur den Namen
  267.                   der zuletzt übertragenen Datei!
  268.  
  269. ÖffneFenster    - Bestimmt, ob während der Übertragung ein Fenster geöffnet
  270.                   werden  soll,  in dem Informationen über den Fortgang der
  271.                   Übertragung angezeigt werden.
  272.  
  273.                   0 = kein Fenster soll geöffnet werden.
  274.                   1 = ein Fenster soll geöffnet werden.
  275.                   2 = ein  Fenster  soll  geöffnet,  aber  nicht  aktiviert
  276.                       werden.
  277.  
  278. Bildschirm      - Dieser  Parameter operiert zusammen mit dem Parameter für
  279.                   `ÖffneFenster'.   Er bestimmt, auf welchem Bildschirm das
  280.                   Fenster  -  wenn  überhaupt - geöffnet werden soll.  Hier
  281.                   übergibt   man   die   Adresse  der  Screen-Struktur  des
  282.                   jeweiligen  Bildschirmes,  oder  den  Wert  NULL,  um das
  283.                   Fenster auf dem Workbench-Bildschirm zu öffnen.
  284.  
  285.    Diese  Routine  liefert  einen  Wert  zurück,  der  über  den Erfolg des
  286. Transfers  informiert.   Ist  dieser  Wert gleich 0, so ist die Übertragung
  287. fehlgeschlagen  oder  abgebrochen  worden.  Ist der Wert ungleich 0, so ist
  288. die Übertragung geglückt.
  289.  
  290.                                      *
  291.  
  292. Erfolg = SendFile(Name, ÖffneFenster, Bildschirm)
  293.   D0               A0       D0            A1
  294.  
  295.  
  296. Name            - Der  Name der zu verschickenden Datei.  Der Name wird als
  297.                   durch ein Nullbyte abgeschlossene Zeichenkette übergeben.
  298.                   In  diese  Zeichenkette  wird  auch  der Name der zuletzt
  299.                   übertragenen  Datei  eingetragen, die Zeichenkette sollte
  300.                   mindestens 256 Zeichen lang sein.
  301.  
  302. ÖffneFenster    - Bestimmt, ob während der Übertragung ein Fenster geöffnet
  303.                   werden  soll,  in dem Informationen über den Fortgang der
  304.                   Übertragung angezeigt werden.
  305.  
  306.                   0 = kein Fenster soll geöffnet werden.
  307.                   1 = ein Fenster soll geöffnet werden.
  308.                   2 = ein  Fenster  soll  geöffnet,  aber  nicht  aktiviert
  309.                       werden.
  310.  
  311. Bildschirm      - Dieser  Parameter operiert zusammen mit dem Parameter für
  312.                   `ÖffneFenster'.   Er bestimmt, auf welchem Bildschirm das
  313.                   Fenster  -  wenn  überhaupt - geöffnet werden soll.  Hier
  314.                   übergibt   man   die   Adresse  der  Screen-Struktur  des
  315.                   jeweiligen  Bildschirmes,  oder  den  Wert  NULL,  um das
  316.                   Fenster auf dem Workbench-Bildschirm zu öffnen.
  317.  
  318.    Diese  Routine  liefert  einen  Wert  zurück,  der  über  den Erfolg des
  319. Transfers  informiert.   Ist  dieser  Wert gleich 0, so ist die Übertragung
  320. fehlgeschlagen  oder  abgebrochen  worden.  Ist der Wert ungleich 0, so ist
  321. die Übertragung geglückt.
  322.  
  323.                                      *
  324.  
  325. Erfolg = SendMultipleFiles(Namen, ÖffneFenster, Bildschirm)
  326.   D0                        A0       D0            A1
  327.  
  328.  
  329. Name            - Die  Adresse  einer  Reihe von Adresswerten von mit einem
  330.                   Nullbyte    abgeschlossenen    Zeichenketten.    In   `C'
  331.                   entspräche      dies      z.B.       der     Konstruktion
  332.                   `char *Namen[123]', in anderen Sprachen kann man sich die
  333.                   verlangte  Datenstruktur  als  ein  Feld  von Langwörtern
  334.                   vorstellen,   von   denen   jedes   die   Adresse   einer
  335.                   Zeichenkette enthält:
  336.  
  337.                                  Feld[ 0 ] -> "Dateiname 0"
  338.                                  Feld[ 1 ] -> "Dateiname 1"
  339.                                  Feld[ 2 ] -> "Dateiname 2"
  340.  
  341.                                  :
  342.                                  :
  343.  
  344.                                  Feld[n-1] -> "Dateiname n-1"
  345.                                  Feld[ n ] -> 0
  346.  
  347.                      Wie man an dieser Tabelle schon sieht, muß der Adresse
  348.                   des  letzten  Dateinamens  eine  Null  folgen,  sodaß die
  349.                   Library  weiß,  welche  die  letzte zu übertragende Datei
  350.                   war.
  351.                      Der    Inhalt    dieses    Feldes    wird    von   der
  352.                   Übertragungsroutine nicht verändert.
  353.  
  354. ÖffneFenster    - Bestimmt, ob während der Übertragung ein Fenster geöffnet
  355.                   werden  soll,  in dem Informationen über den Fortgang der
  356.                   Übertragung angezeigt werden.
  357.  
  358.                   0 = kein Fenster soll geöffnet werden.
  359.                   1 = ein Fenster soll geöffnet werden.
  360.                   2 = ein  Fenster  soll  geöffnet,  aber  nicht  aktiviert
  361.                       werden.
  362.  
  363. Bildschirm      - Dieser  Parameter operiert zusammen mit dem Parameter für
  364.                   `ÖffneFenster'.   Er bestimmt, auf welchem Bildschirm das
  365.                   Fenster  -  wenn  überhaupt - geöffnet werden soll.  Hier
  366.                   übergibt   man   die   Adresse  der  Screen-Struktur  des
  367.                   jeweiligen  Bildschirmes,  oder  den  Wert  NULL,  um das
  368.                   Fenster auf dem Workbench-Bildschirm zu öffnen.
  369.  
  370.    Diese  Routine  liefert  einen  Wert  zurück,  der  über  den Erfolg des
  371. Transfers  informiert.   Ist  dieser  Wert gleich 0, so ist die Übertragung
  372. fehlgeschlagen  oder  abgebrochen  worden.  Ist der Wert ungleich 0, so ist
  373. die Übertragung geglückt.
  374.    Man   sollte   nicht   erwarten,   daß   sich   diese  Routine  auch  um
  375. Pattern-Matching  und  ähnlichen  Luxus kümmert, es wird immer versucht die
  376. jeweiligen   Dateien   unter   den   gegebenen   Namen   zu  öffnen.   Wird
  377. Pattern-Matching benötigt, so müssen die zu übertragenden Dateien ermittelt
  378. werden, bevor die Übertragung stattfindet.
  379.    Ob  diese  Funktion  ihren  Zweck  erfüllen  kann,  hängt  stark von der
  380. verwendeten  xpr.library  ab;  unterstützt  diese keinen Batch-Transfer, so
  381. wird zumindest versucht, die erste zu übertragende Datei zu verschicken.
  382.  
  383.                                      *
  384.  
  385. Erfolg = GetOptions(Puffer)
  386.   D0                  A0
  387.  
  388. Puffer          - Hier   werden  die  aktuell  eingestellten  Optionen  der
  389.                   geöffneten    xpr.library   abgelegt.    Es   wird   eine
  390.                   Zeichenkette  erwartet,  die  mindestens 256 Zeichen lang
  391.                   ist.
  392.  
  393.    Diese  Routine liefert einen Wert zurück, der über den Erfolg der Aktion
  394. informiert.   Ist dieser gleich 0, so konnten die Optionen nicht ausgelesen
  395. werden.   Ist er ungleich 0, so enthält der übergebene Puffer die mit einem
  396. Nullbyte abgeschlossenen aktuellen Optionen.
  397.  
  398.                                      *
  399.  
  400. Erfolg = SetOptions(Optionen)
  401.   D0                   A0
  402.  
  403. Optionen        - Die  zu  setzenden Optionen für die aktuelle xpr.library.
  404.                   Wird   als   mit  einem  Nullbyte  beendete  Zeichenkette
  405.                   erwartet.
  406.  
  407.    Diese  Routine liefert einen Wert zurück, der über den Erfolg der Aktion
  408. informiert.   Ist  dieser  gleich  0, so konnten die Optionen nicht gesetzt
  409. werden.  Ist er ungleich 0, so wurden die Optionen korrekt gesetzt.
  410.  
  411.                                      *
  412.  
  413. Fehler = InstallTransferNote(Note)
  414.   D0                          A0
  415.  
  416. Note            - Die  Adresse  einer  `C'-Struktur,  die man sich auch als
  417.                   eine Aufreihung von dreizehn Langwörtern vorstellen kann,
  418.                   sie sieht wie folgt aus:
  419.  
  420.                       struct TransferNote
  421.                       {
  422.                          LONG tn_Continue;     /* Ist dieser Wert gleich 0,
  423.                                                 * so wird der Transfer-
  424.                                                 * vorgang sofort ab-
  425.                                                 * gebrochen.
  426.                                                 */
  427.  
  428.                          LONG tn_CarrierDetect;/* Der Inhalt dieser Variable
  429.                                                 * gibt an, ob das Modem ein
  430.                                                 * Trägersignal (Carrier)
  431.                                                 * erkennt. Ist dieses Signal
  432.                                                 * nicht mehr vorhanden, ist
  433.                                                 * die Verbindung unterbrochen
  434.                                                 * worden.
  435.                                                 */
  436.  
  437.                          LONG tn_Seconds;      /* Anzahl der Sekunden, die
  438.                                                 * der Transfervorgang noch
  439.                                                 * dauern wird. Vorsicht!
  440.                                                 * dieser Wert kann von
  441.                                                 * Anfang an gleich 0 sein
  442.                                                 * und sich während des
  443.                                                 * gesamten Transfers
  444.                                                 * nicht verändern.
  445.                                                 */
  446.  
  447.                          LONG tn_Bytes;        /* Anzahl der noch zu
  448.                                                 * übertragenden Bytes.
  449.                                                 * Auch dieser Wert kann
  450.                                                 * von Anfang an gleich 0
  451.                                                 * sein und sich während
  452.                                                 * des gesamten Transfers
  453.                                                 * nicht verändern.
  454.                                                 */
  455.  
  456.                          APTR tn_UserData;     /* Ein Eintrag, der vom
  457.                                                 * Benutzer für seine
  458.                                                 * Zwecke verwendet
  459.                                                 * werden kann.
  460.                                                 */
  461.  
  462.                          char *tn_CurrentFile; /* Adresse einer Zeichenkette,
  463.                                                 * die den Namen der gerade
  464.                                                 * übertragenen Datei enthält.
  465.                                                 * Vorsicht: dieser Wert kann
  466.                                                 * auch NULL (0) sein, wenn
  467.                                                 * gerade keine Datei übertragen
  468.                                                 * wird.
  469.                                                 */
  470.  
  471.                          LONG tn_FilesToGo;    /* Soweit bekannt, enthält diese
  472.                                                 * Variable die Anzahl der noch
  473.                                                 * zu übertragenden Dateien
  474.                                                 * (0 = die letzte Datei wird
  475.                                                 * gerade verschickt).
  476.                                                 */
  477.  
  478.                          LONG tn_ProtocolName; /* Name einer Datei, in der die
  479.                                                 * Namen aller empfangenen und
  480.                                                 * verschickten Dateien eingetragen
  481.                                                 * werden. Steht hier eine Null,
  482.                                                 * so wird keine Protokolldatei
  483.                                                 * angelegt.
  484.                                                 */
  485.  
  486.                          LONG tn_Extension;    /* Anzahl der dieser Strukturform
  487.                                                 * noch folgenden Langwörter (für
  488.                                                 * künftige Erweiterungen reserviert).
  489.                                                 */
  490.  
  491.                          LONG tn_WatchCarrier; /* Sofern tn_Extension einen Wert >= 1
  492.                                                 * enthält, wird der Library über den
  493.                                                 * Inhalt dieses Langworts mitgeteilt,
  494.                                                 * ob bei Verlust des Trägersignals
  495.                                                 * der Transfer abgebrochen werden
  496.                                                 * soll. Falls Ja, ist hier eine 1,
  497.                                                 * falls Nein, eine 0 einzutragen.
  498.                                                 */
  499.  
  500.                          LONG tn_Aborted;      /* Sofern tn_Extension einen Wert >= 2
  501.                                                 * enthält, wird der Library über den
  502.                                                 * Inhalt dieses Langworts mitgeteilt,
  503.                                                 * ob der Transfer durch den Anwender
  504.                                                 * abgebrochen wurde.
  505.                                                 */
  506.  
  507.                          LONG tn_Error;        /* Sofern tn_Extension einen Wert >= 3
  508.                                                 * enthält, wird der Library über den
  509.                                                 * Inhalt dieses Langworts mitgeteilt,
  510.                                                 * ob der Transfer aufgrund eines
  511.                                                 * Fehlers abgebrochen wurde. Ist der
  512.                                                 * hier eingetragene Wert = 0, so ist
  513.                                                 * kein Fehler aufgetreten, ist er 1,
  514.                                                 * liegt ein AmigaDOS-Fehler vor, bei
  515.                                                 * 2 ist ein Schnittstellenfehler
  516.                                                 * aufgetreten.
  517.                                                 */
  518.  
  519.                          LONG tn_ErrorCode;    /* Sofern tn_Extension einen Wert >= 4
  520.                                                 * enthält, wird der Library über den
  521.                                                 * Inhalt dieses Langworts mitgeteilt,
  522.                                                 * aufgrund welchen Fehlers der Transfer
  523.                                                 * abgebrochen wurde. Dies ist entweder
  524.                                                 * ein AmigaDOS-Fehlercode, ein Fehlercode
  525.                                                 * der Schnittstelle oder der Wert 1000,
  526.                                                 * der angibt, daß das Carrier-Signal
  527.                                                 * verlorengegangen ist.
  528.                                                 */
  529.                       };
  530.  
  531.    Diese  Routine liefert einen Wert ungleich 0 zurück, wenn beim Eintragen
  532. ein   Fehler   aufgetreten  ist  (die  jeweiligen  Fehlerwerte  sind  unter
  533. `TransferSetup'  aufgeführt),  ein Wert gleich 0 wird zurückgeliefert, wenn
  534. kein Fehler aufgetreten ist.
  535.    Typischerweise  wird  diese Funktion von einem separat laufenden Process
  536. benutzt,  um  den  im Transfer befindlichen Process überwachen und notfalls
  537. abbrechen  zu  können.   Die übergebene `TransferNote'-Struktur muß während
  538. des    gesamten    Transfervorganges   erhalten   bleiben,   sonst   können
  539. Systemabstürze  die  Folge sein.  Der Bezug auf die Struktur bleibt bis zum
  540. Schließen   der  Library  oder  bis  zum  nächsten  Aufruf  der  Funktionen
  541. TransferSetupShared() und TransferSetup() erhalten.
  542.  
  543.    Zum   Format   der   Protokolldatei:    wird  eine  Datei  gelesen  oder
  544. beschrieben,  wenn  sie  verschickt  oder  empfangen wird, so wird ihr Name
  545. zusammen  mit  dem  jeweiligen  Zugriffsmodus  (`R'  für Empfangen, `S' für
  546. Verschicken)  in  die  Datei  geschrieben, deren Name unter tn_ProtocolName
  547. eingetragen  ist.   Typischerweise  sieht  der  Inhalt dieser Datei am Ende
  548. einer Übertragung folgendermaßen aus:
  549.  
  550.                       R Work:Download/EmpfangeDatei1
  551.                       R Work:Download/EmpfangeDatei2
  552.                                      :
  553.                                      :
  554.                                     etc.
  555.  
  556. An  die  unter  tn_ProtocolName  angegebene  Datei  werden  die  Namen  der
  557. empfangenen/verschickten    Dateien    _angehängt_,    sie   wird   _nicht_
  558. überschrieben.
  559.    Wird  eine  Datei  nicht korrekt verschickt/empfangen, so wird statt der
  560. Großbuchstaben "R" / "S" ein Kleinbuchstabe "r" / "s" vorangestellt.
  561.    Zum Schluß wird an die Liste der Dateinamen eine Zeile mit statistischen
  562. Daten angehängt, die folgenden Aufbau hat:
  563.  
  564.                + Files <Anzahl> Bytes <Anzahl> CPS <Anzahl>
  565.  
  566.    Es  wird  die  Anzahl  der  empfangenen Dateien, die Anzahl der empfang-
  567. enen  Dateien    und  die  durchschnittliche Übertragungsgeschwindigkeit in
  568. Zeichen pro Sekunde angegeben.
  569.                                      
  570. ================================ Anwendung ================================
  571. ===========================================================================
  572. Für  `C'  habe  ich  eine  Header-Datei  bereitgestellt, die Prototypen und
  573. Übergabewerte  enthält,  Linker-Bibliotheken sind ebenfalls vorhanden.  Für
  574. alle anderen Sprachen muß man sich mit der .fd-Datei behelfen.
  575.  
  576.        Die übliche Reihenfolge der Aufrufe sähe z.B. wie folgt aus:
  577.  
  578.         MetaXprBase = OpenLibrary("metaxpr.library",0);
  579.  
  580.         :
  581.         :
  582.  
  583.         Fehler = TransferSetup("serial.device",0,"xprzmodem.library",
  584.                                 2400,8,1,0,0);
  585.  
  586.         :
  587.         :
  588.  
  589.         Erfolg = ReceiveFile("Datei",0,0);
  590.  
  591.         :
  592.         :
  593.  
  594.         Erfolg = SendFile("Datei",1,Screen);
  595.  
  596.         :
  597.         :
  598.  
  599.         CloseLibrary(MetaXprBase);
  600.  
  601.    Wem  diese  paar Zeilen nicht helfen, der kann mir seine Fragen entweder
  602. brieflich, oder auf elektronischem Wege über Z-Net oder Usenet stellen.
  603.  
  604.  
  605. ====================== Anschrift & Bitte des Autors =======================
  606. ===========================================================================
  607. Die  Benutzung  der  metaxpr.library  ist  kostenfrei,  ich  verlange keine
  608. Spenden,  noch  erwarte  ich  sie.  Die einzige Auflage, die ich mache, ist
  609. die, daß jeder, der neue Supportroutinen für die Bibliothek schreibt, diese
  610. dem  MetaXPR-Paket hinzufügt, oder sie mir zuschickt.  Auf diese Weise soll
  611. Jedermann Zugang zur Nutzung der Bibliothek erhalten.
  612.  
  613.                              Meine Anschrift:
  614.  
  615.                                Olaf Barthel
  616.                              Brabeckstraße 35
  617.                             D-3000 Hannover 71
  618.  
  619.                         Z-Netz: O.BARTHEL@A-LINK-H
  620.                       Internet: olsen@sourcery.mxm.sub.org
  621.                                 o.barthel@a-link-h.comlink.de
  622.  
  623.  
  624. ========================= Entwicklungsgeschichte ==========================
  625. ===========================================================================
  626. V4.0    Erweiterung   der   Überwachungsfunktionen,   verschiedene   Fehler
  627.         erschlagen.
  628.  
  629. V3.6-   Interne Versionen.
  630. V3.9
  631.  
  632. V3.5    Die Protokollierung der empfangenen und verschickten Dateien ist um
  633.         statistische   Daten  erweitert  worden.  Ebenfalls  ist  es  jetzt
  634.         möglich, den Transfer bei Verlust des Carrier-Signales abbrechen zu
  635.         lassen.
  636.  
  637. V3.4    Die   Library   unterstützt   andere   Treiber   als  das  Original
  638.         serial.device    jetzt   besser,   es   ist   jetzt   möglich,  die
  639.         Transferaktionen  in  einer  Datei mitprotokollieren zu lassen, das
  640.         Transferfenster kann jetzt auch inaktiv geöffnet werden.
  641.  
  642. V3.3    Einige  interne  Änderungen  sind  notwendig  geworden; die Library
  643.         meldet  jetzt  korrekt,  wenn ein Transfer abgebrochen wurde und es
  644.         erscheint  kein  AmigaDOS-Requester  mehr,  wenn  Diskettenprobleme
  645.         auftreten  (dieses  Feature ist zur Unterstützung der automatischen
  646.         Ausführung von Netcalls gedacht).
  647.  
  648. V3.1    Die  Library  wurde  wieder einmal um eine neue Funktion erweitert:
  649.         `SendMultipleFiles'      ist      hinzugekommen.       Auch     die
  650.         TransferNote-Struktur  ist  um einige Felder erweitert worden, auch
  651.         die Carrier-Erkennung sollte jetzt funktionieren.
  652.  
  653. V3.0    Die   Library   wurde   um   die  Funktion  `InstallTransferNote()'
  654.         erweitert.
  655.  
  656. V2.0    Es  gibt  die  neue  Funktion  `TransferSetupShared()', die Library
  657.         sollte  intern  jetzt etwas stabiler arbeiten, ein paar Fehler sind
  658.         beseitigt.
  659.  
  660. V1.2    Das Fenster verträgt sich auch mit anderen Systemfonts als topaz 8,
  661.         werden  andere  Tasten  als  ^C  oder  Escape  gedrückt,  hängt der
  662.         Transfervorgang  nicht  mehr,  die  Bibliothek läßt sich auch unter
  663.         Kickstart  2.0  öffnen.   Der Send und Receive übergebene Dateiname
  664.         enthält  nach  der  Übertragung  den Namen der zuletzt übertragenen
  665.         Datei.
  666.  
  667. V1.1    Erste öffentliche Verbreitung.
  668.