Topic       : TOS - das Betriebssystem
Author      : 
Version     : tos.hyp (5. März 2013)
Subject     : Programmieren/Atari
Nodes       : 3001
Index Size  : 93602
HCP-Version : 5
Compiled on : Atari
@charset    : atarist
@lang       : 
@default    : Titel
@help       : 
@options    : +g -i -s +x +zz -t4
@width      : 70
View Ref-File11.23.3  Wie verwende ich eine Shared Libraries?                   TOS

Zunächst benötigt man zum Aufruf der beiden neuen DOS-Funktionen das 
Objektmodul SLB_BIND, dazu muß man die Datei SLB.H einbinden.

Für jede benutzte Bibliothek deklariert man einen Deskriptor vom Typ 
SHARED_LIB und einen Funktionszeiger vom Typ SLB_EXEC.

Jede Bibliothek wird mit Slbopen() geöffnet (das Öffnen und Schließen 
sollte nur im User-Modus erfolgen), dabei werden folgende Parameter 
übergeben:

 char *name   Der Name der Bibliothek, in Großschrift, inkl. Extension 
              (".SLB"). Der Bibliotheksname ist gleichzeitig 
              Dateiname.
 char *path   Wenn dieser Parameter nicht NULL ist, wird hier zuerst 
              nach der Bibliothek gesucht (der Pfad muß in MagiC 5.20 
              mit '\' abgeschlossen sein; dies ist in MagiC 6 nicht 
              mehr nötig). Der Pfad sollte absolut sein, damit die 
              Shared Library weiß, wo sie liegt. Wenn der Parameter 
              NULL ist oder die Bibliothek im angegebenen Pfad nicht 
              gefunden wurde, wird im XTENSION-Ordner gesucht.
              Ab MagiC 6 wird die Environment-Variable SLBPATH 
              ausgewertet. Sie enthält wie PATH eine Liste der 
              Suchpfade, jeweils durch ';' getrennt. Ist die Variable 
              definiert, wird nicht mehr extra im XTENSION-Ordner 
              gesucht.
 LONG min_ver Minimal notwendige Versionsnummer der Bibliothek.
              Wenn ein Programm etwa die Version 3 benötigt, die 
              Bibliothek aber erst Version 2 ist, wird ERANGE 
              zurückgegeben. Die tatsächliche Versionsnummer der 
              Bibliothek wird als Rückgabewert geliefert.
 SHARED_LIB *sl Zeiger auf den Deskriptor. Wenn die Bibliothek 
              geöffnet wurde, wird hier der Deskriptor eingetragen.
 SLB_EXEC *fn Zeiger auf den Funktionszeiger. Wenn die Bibliothek 
              geöffnet wurde, wird hier der Funktionszeiger 
              eingetragen.

Rückgabewert kann sein:

  >= 0        Alles OK, Versionsnummer der Bibliothek.
  ERANGE      Versionsnummer zu niedrig
  EACCDN      Bibliothek schon von diesem Prozeß geöffnet
  EFILNF      Bibliothek nicht gefunden
  ENSMEM      zuwenig Speicher
  ...         andere Fehlercodes.

Die Bibliothek kann nun verwendet und schließlich mit Slbclose() 
wieder geschlossen werden. Dies ist nicht unbedingt notwendig, da alle 
geöffneten Bibliotheken bei Programmende automatisch geschlossen 
werden, aber es ist guter Programmierstil. Auf keinen Fall darf eine 
Bibliothek mehrmals geschlossen werden, der Kernel kann solche Fehler 
nicht erkennen.

Einige Bibliotheken, wie z.B. EDITOBJC.SLB, installieren neue 
Systemaufrufe, in diesem Fall die AES-Aufrufe 210..217. Für diese 
Bibliotheken wird der Funktionszeiger nicht benötigt. Ansonsten werden 
alle Funktionen der Bibliothek über den Funktionszeiger aufgerufen. 
Die Bibliotheks-Aufruf-Funktion ist folgendermaßen deklariert:

 typedef LONG (cdecl *SLB_EXEC)( SHARED_LIB *sl, LONG fn,
        WORD nargs, ... );

Da leider PureC hier einen Fehler hat, mußte ich die Funktion 
notgedrungen deklarieren als "typedef LONG (*SLB_EXEC)( void , ... );" 
Damit sind leider alle Typüberprüfungen verbaut. Also Vorsicht!

Der Aufruf erwartet folgende Parameter:

     Den Deskriptor der Bibliothek
     Ein Langwort (!) für die Funktionsnummer
     Ein WORD, das die Anzahl der Argumente in WORDs
               (d.h. alle "..."-Argumente) angibt
     weitere Argumente je nach Funktion

Am besten geschieht der Aufruf über ein Makro, das in einer 
Headerdatei für die Bibliothek definiert werden sollte, z.B.:

JPEG.H:

#define SLBJPEG_WANDELN (a,b) (*slbjpeg_exec)(slbjpeg, 7L, 4, a, b)

Hierbei werden <slbjpeg_exec> und <slbjpeg> bei Slbopen() ermittelt, 
7L ist die Funktionsnummer für den Aufruf WANDELN, 4 bezeichnet die 
Länge der folgenden Argumente (a und b sind zwei Zeiger => 2*4 Bytes 
=> 4 WORDs), a und b sind die Argumente der Funktion WANDELN.

Wenn die Funktion nicht vorhanden ist (die Bibliothek enthält für 
diese Funktion einen Nullzeiger, oder die Funktionsnummer ist höher 
als die Anzahl der tatsächlich vorhandenen Funktionen), erhält man 
EINVFN als Funktionsergebnis (tatsächlich klappt das erst ab MagiC 6 
korrekt).