home *** CD-ROM | disk | FTP | other *** search
/ M.u.C.S. Disc 2000 / MUCS2000.iso / anwend / gemar306 / plugin / plugins.txt < prev    next >
Text File  |  1997-01-21  |  11KB  |  303 lines
  1.  
  2.  
  3. PlugIns für GEMAR                                                                             ╛ Steffen Engel 1992-94
  4.  
  5. 25.05.94
  6.  
  7.  
  8. ALLGEMEINES
  9.  
  10.     In dieser Datei werden alle nötigen Informationen zu PlugIns gegeben, der 
  11.     aktuelle Stand der von GEMAR installierten PlugIn-Calls, die Liste der aktuell 
  12.     existierenden PlugIns und der aktuelle Stand der PlugIns und ihrer 
  13.     Programmierung.
  14.  
  15.     Die mit GEMAR gelieferten PlugIns sind grundsätzlich alle deaktiviert, indem
  16.     die Namen mit PLX enden.
  17.  
  18.     Bitte beurteilen Sie selbst, welche PlugIns für Sie sinnvoll sind.
  19.  
  20.  
  21. WAS SIND PLUGINS?
  22.  
  23.     Um GEMAR mit weiteren Fähigkeiten auszustatten, wurde ein Konzept entworfen, 
  24.     mit dem externe Programme als Erweiterung hinzugeladen werden können.
  25.  
  26.     Dabei wird von GEMAR an bestimmten Stellen einfach kontrolliert, ob ein zu 
  27.     diesem Zweck gehörendes PlugIn existiert, und ruft es gegebenenfalls auf.
  28.  
  29.     Grundsätzlich wurde das Konzept relativ einfach gehalten, da es dadurch 
  30.     einerseits einfach zu verstehen und programmieren ist und andererseits kein 
  31.     vollständig modulares Programmierungssystem entworfen werden sollte.
  32.  
  33.     Mit diesem Konzept sind nur kleine Erweiterungen oder Ersetzungen von Teilen 
  34.     von GEMAR möglich.
  35.  
  36.     PlugIns sind vor allem dann sinnvoll, wenn kleine Erweiterungen an GEMAR 
  37.     gemacht werden sollen, die für bestimmte Probleme sinnvoll sind, aber zu 
  38.     speziell sind, um allgemein in GEMAR eingebaut zu werden.
  39.  
  40.     PlugIns werden von GEMAR grundsätzlich im Ordner PLUGIN im GEMAR-Pfad
  41.     gesucht.
  42.  
  43.  
  44. AUFBAU UND PROGRAMMIERUNG VON PLUGINS
  45.  
  46.     PlugIns werden grundsätzlich als Pozeduren aufgerufen. Als Methode wurde ein
  47.     ähnlicher Weg gewählt wie bei CPX-Modulen.
  48.  
  49.     Zur Identifikation tragen PlugIns zur Zeit einen 512-Byte langen Kopf:
  50.  
  51.     TYPE tPlugHead
  52.                 = RECORD
  53.                         Magic             : lCARDINAL;                            (* 'Plug' *)
  54.                         Identify        : ARRAY[0..19] OF CHAR;     (* Kontrolle für Programm *)
  55.                         SlotIdent     : ARRAY[0..19] OF CHAR;     (* Identifikation für Verwendung *)
  56.                         Info                : ARRAY[0..467] OF CHAR;    (* Beschreibung *)
  57.                     END;
  58.  
  59.     Identify dient dabei dazu, zu erkennen, ob dieses Plugin überhaupt für das
  60.     laufende Programm ist. Bei Gemar mu₧ Identify immer 'Gemar' sein.
  61.     SlotIdent dient zur Erkennung, ob das PlugIn für den Slot geeignet ist.
  62.     Dies dient als Schutz, da₧ zB ein Plugin für die Index-Bearbeitung nicht
  63.     für SCSI-Routinen eingeklinkt wird.
  64.  
  65.  
  66.     PlugIns werden geladen und danach wird der Rumpf des PlugIns mit einem Zeiger
  67.     auf folgende Struktur aufgerufen:
  68.  
  69.     tPlugEnvironment
  70.         = RECORD
  71.                 (* aktuelle Parameterversion = 1.00 = 0100H *)
  72.                 Version  : sINTEGER;                                                    (* Version zeigt Umfang der Parameter an     *)
  73.                 Private  : ADDRESS;                                                     (* spezielle Parameter für den Rumpf             *)
  74.                 ApplId     : sINTEGER;                                                    (* Applikationsid des rufenden Programmes  *)
  75.                 VDIHandle: sINTEGER;                                                    (* Workstation des Hauptprogrammes                 *)
  76.                 PlugPath : POINTER TO ARRAY[0..512] OF CHAR;    (* Name und Pfad des PlugIn, kann auch
  77.                                                                                                                  relativ sein                                                      *)
  78.                 Alert      : PROCEDURE((* def *) sINTEGER, VAR (* msg *) STRING) : sINTEGER;
  79.             END;
  80.  
  81.     In C sieht das entsprechend so aus:
  82.  
  83.     typedef struct
  84.         {
  85.             int     Version;
  86.             void    *private;
  87.             int     ApplId;
  88.             int     VDIHandle;
  89.             char    *PlugPath;
  90.             int     (*Alert) (int defbutt, char *msg);
  91.         } PLUGPARMS;
  92.  
  93.  
  94.     Die Struktur wird grundsätzlich abwärtskompatibel sein, d.h. bei erweiterten 
  95.     Versionen kommen zusätzliche Parameter hinzu und die Versionsnummer wird 
  96.     erhöht.
  97.  
  98.     Nach einer evtl. nötigen Initialisierung (zB Abfragen, ob das Modul überhaupt 
  99.     aktiviert werden soll) mu₧ das PlugIn mit einem Zeiger auf eine Tabelle
  100.     von Funktionen antworten:
  101.  
  102.     TYPE    tpPlugProcs = POINTER TO tPlugProcs;
  103.                 tPlugProc     = PROCEDURE((* par : *) ADDRESS) : lINTEGER;
  104.                 tPlugProcs    = RECORD
  105.                                                 num : SHORTINT;                 (* Anzahl der Funktionen *)
  106.                                                 Procs : ARRAY[0..07FFFH] OF tPlugProc;
  107.                                             END;
  108.  
  109.     Ein Null-Zeiger zeigt an, da₧ das PlugIn nicht aktiviert werden soll (oder
  110.     bereits fertig ist).
  111.  
  112.     Diese Funktionen werden dann zur eigentlichen Verwendung ein- oder mehrmals
  113.     aufgerufen. Als Parameter wird ein Zeiger übergeben, der auf die zu 
  114.     bearbeitenden Daten zeigt.
  115.  
  116.     Bitte beachten Sie, da₧ UNBEDINGT aller Speicher bei der Deinitialisierung 
  117.     des PlugIns freigegeben wird, da der Speicher nicht durch das Freigeben des
  118.     PlugIn freigeben wird!
  119.  
  120.     Die Aufforderung zur Deinitialisierung erfolgt durch Aufruf der Funktion 0
  121.     mit -1 (0FFFFFFFFH) als Parameter.
  122.  
  123.     Als Beispiel sollten Sie sich die beiliegenden PlugIns ansehen, insbesondere
  124.     PLUGPARM.D
  125.  
  126. PARAMETER IN GEMAR
  127.  
  128.     Als Standardstruktur wird von GEMAR in private ein Zeiger auf die folgende
  129.     Struktur übergeben:
  130.  
  131.     TYPE tPlugPrivate = RECORD
  132.                                             Version : SHORTCARD;        (* = 0200H = 2.00 *)
  133.                                             special : ADDRESS;            (* Spezielles für Art des PlugIn *)
  134.                                             StrHandle : SHORTCARD;
  135.                                             StrMaxLen : LONGCARD;
  136.                                             BlockLen: SHORTCARD;        (* Blocklänge des Streamers *)
  137.                                             ScsiIn    : PROCEDURE ((* ScsiCmd *) tpScsiCmd) : SHORTINT;
  138.                                             ScsiOut : PROCEDURE ((* ScsiCmd *) tpScsiCmd) : SHORTINT;
  139.                                             SuperOn     : PROC;
  140.                                             SuperOff    : PROC;
  141.                                         END;
  142.                                 
  143.                                         In C sieht das so aus:
  144.                                 
  145.                                         typedef struct
  146.                                             {
  147.                                                 unsigned word version;
  148.                                                 void *special;
  149.                                                 word strhandle;
  150.                                                 long strmaxlen;
  151.                                                 word blocklen;
  152.                                                 word (*ScsiIn)    (SCSIPARMS *Parms);
  153.                                                 word (*ScsiOut) (SCSIPARMS *Parms);
  154.                                                 void (*SuperOn) ();
  155.                                                 void (*SuperOff) ();
  156.                                             } tScsiCall;
  157.  
  158.              tScsiCmd     = RECORD
  159.                                             handle            : SHORTCARD;        (* das handle des Gerätes *)
  160.                                             Cmd                 : ADDRESS;            (* Zeiger auf CmdBlock *)
  161.                                             CmdLen            : SHORTCARD;        (* Länge des Cmd-Block *)
  162.                                             Buffer            : ADDRESS;            (* Datenpuffer                 *)
  163.                                             TransferLen : LONGCARD;         (* Übertragungslänge     *)
  164.                                             SenseBuffer : ADDRESS;            (* Puffer für ReqSense (18 Bytes) *)
  165.                                             Timeout         : LONGCARD;         (* Timeout in 1/200 sec *)
  166.                                             Flags             : BITSET;             (* Bitvektor für Ablaufwünsche *)
  167.                                         END;
  168.              tpScsiCmd    = POINTER TO tScsiCmd;
  169.  
  170.                                         Return-Werte für ScsiIn und ScsiOut sind:
  171.                                 
  172.                                         NOSCSIERROR         =     0; (* Kein Fehler                                                                  *)
  173.                                         SELECTERROR         =  -1; (* Fehler beim Selektieren                                          *)
  174.                                         STATUSERROR         =  -2; (* Default-Fehler                                                             *)
  175.                                         PHASEERROR            =  -3; (* ungültige Phase                                                          *)
  176.                                         BSYERROR                =  -4; (* BSY verloren                                                                 *)
  177.                                         BUSERROR                =  -5; (* Busfehler bei DMA-Übertragung                              *)
  178.                                         TRANSERROR            =  -6; (* Fehler beim DMA-Transfer (nichts übertragen) *)
  179.                                         FREEERROR             =  -7; (* Bus wird nicht mehr freigegeben                          *)
  180.                                         TIMEOUTERROR        =  -8; (* Timeout                                                                          *)
  181.                                         DATATOOLONG         =  -9; (* Daten für ACSI-Softtransfer zu lang                  *)
  182.                                         LINKERROR             = -10; (* Fehler beim Senden des Linked-Command (ACSI) *)
  183.                                         TIMEOUTARBIT        = -11; (* Timeout bei der Arbitrierung                                 *)
  184.                                         PENDINGERR            = -12;
  185.                                 
  186.                                         Werte > 0 sind das Statusbyte des SCSI-Gerätes (siehe SCSI-Norm)
  187.  
  188.      ACHTUNG!!!
  189.      BlockLen kann sich während des Betriebes von GEMAR ändern und ist nur gültig,
  190.      wenn ein Band geladen ist!!
  191.  
  192.      special ist dabei ein Spezial-Parameter für das PlugIn, der von der Art des
  193.      PlugIn abhängt.
  194.      Dieser Parameter ist _NUR_ während der Initialisierung des PlugIn gültig und
  195.      mu₧ daher getrennt von der private-Struktur gesichert werden!!
  196.  
  197.      Es reicht, den Zeiger zu sichern, da die Struktur auf die special zeigt,
  198.      nicht flüchtig ist.
  199.  
  200. EXISTIERENDE PLUGINS
  201.  
  202.     Zur Zeit existieren fünf PlugIn-Slots:
  203.     -REQSENSE präzisiert die Fehlermeldungen des Streamers, die in den Request 
  204.                         Sense Daten übergeben werden.
  205.     -INDEX        wird nach jedem Backup aufgerufen und kann entweder den Inhalt eines
  206.                         Bandes ausdrucken, oder in eine Datei schreiben.
  207.                         Darin können INDEX.PLG und SCANINDEX.PLG eingesetzt werden.
  208.     -SCANINDE wird beim Indexscanning aufgerufen. Damit kann eine Datei auf einem 
  209.                         Band gesucht werden.
  210.                         Darin können INDEX.PLG und SCANINDEX.PLG eingesetzt werden.
  211.     -SCSI         Wird bei allen SCSI-Befehlen gerufen und kann damit Anpassungen an
  212.                         exotische Streamer durchführen.
  213.                         Darin können die folgenden Plugins eingesetzt werden:
  214.                         -SPACE.PLG    wird bei Space-Operationen des Streamers gerufen, um
  215.                                                 ein modifziertes Spacing durchzuführen
  216.                         -QFA.PLG        wird bei eingeschaltetem Quick File Access für die
  217.                                                 Funktionen benutzt.
  218.                                                 Dabei ist egal, welche Art eingeschaltet ist (Seek oder
  219.                                                 Locate)
  220.     -Index-Import Wird bei unbekanntem Band-Header gerufen. Damit sind Restores
  221.                         von GEMAR-fremden Bändern möglich.
  222.  
  223.     SCANINDE und INDEX besitzen gleiche Aufrufe, da₧ hei₧t, Sie können INDEX.PLG 
  224.     in SCANINDE.PLG umbenennen und damit per 'Scannen' nachträglich den Inhalt des 
  225.     Bandes in eine Datei schreiben lassen.
  226.  
  227.  
  228. EXISTIERENDE PLUGIN-AUFRUFE
  229.  
  230.  
  231.     1. Namentliche installierte PlugIns:
  232.  
  233.  
  234.     -INDEX.PLG:
  235.         Aufruf        : Nach einem Backup
  236.         Name            : INDEX.PLG
  237.         Anzahl        : 1  (Laden nach Name)
  238.         SlotIdent : 'Index'
  239.         Prozeduren: 2 Prozeduren für Aufruf
  240.                                 1. Prozedur : Der Call bekommt Zeiger auf Index-Einträge,
  241.                                                             jeweils einen Ordner alphabetisch durchlaufen,
  242.                                                             danach den nächsttieferen Ordner.
  243.                                                             Auf dieser Basis wäre zB ein Exporter in eine
  244.                                                             Datenbank möglich.
  245.                                                             übergebene Struktur: s. INDEX.M
  246.                                 2. Prozedur     Zeiger auf den Index-Header.
  247.                                                             Ein Aufruf zeigt an, da₧ ein neuer Index gelesen
  248.                                                             wurde und der Header mit den Daten gefüllt ist.
  249.  
  250.     -SCANINDEX.PLG:
  251.         Aufruf        : bei Index-Scanning
  252.         Name            : SCANINDE.PLG
  253.         Anzahl        : 1  (Laden nach Name)
  254.         SlotIdent : 'Index'
  255.         Prozeduren: 2 Prozeduren für Aufruf, wie INDEX
  256.                                 retour = 1 bricht Scanning ab und wählt den aktuellen Index
  257.  
  258.  
  259.     2. Typbasiert installierte PlugIns:
  260.  
  261.     -REQSENSE:
  262.         Aufruf        : Nach einem Scsi-Fehler (Check Condition auf Streamerzugriff).
  263.         Anzahl        : 1
  264.         SlotIdent : 'REQSENSE'
  265.         Prozeduren: 1 Prozedur für Aufruf
  266.         Parameter : Zeiger auf Request-Sense-Daten, die vorher vom SCSI-Gerät geholt 
  267.                                 wurden.
  268.         Antwort     : Zeiger auf einen (nullterminierten) String, der in die Alertbox 
  269.                                 eingesetzt wird ('Check Condition(%s)')
  270.  
  271.     -SCSI:
  272.         Aufruf        : Wird bei allen SCSI-Kommandos gerufen
  273.         Anzahl        : 1
  274.         SlotIdent : 'SCSI'
  275.         Prozeduren: 2 Prozeduren für Aufruf
  276.                                 1. Prozedur ist SCSIIn
  277.                                 2. Prozedur ist SCSIOut
  278.         Parameter : Zeiger auf die ScsiStruktur
  279.         Bemerkung : Aufruf im Supervisor-Modus!
  280.  
  281.     -Index-Import:
  282.         Aufruf        : Wird bei unbekanntem Band-Header gerufen
  283.         Anzahl        : frei
  284.         SlotIdent : 'Index-Import'
  285.         Bemerkung : Dokumentation nur für Programmierer von Importern.
  286.  
  287.  
  288.  
  289.     Weitere Aufrufe richte ich gerne ein, Ideen sind immer willkommen.
  290.  
  291.  
  292.  
  293. HISTORY
  294.  
  295. 17.07.94
  296.     -Umstellung auf den Header vor dem PlugIn
  297.     -Umstellung der private-Parameter.
  298.  
  299. 20.12.94
  300.     -Umstellung auf Slotbasierte PlugIns
  301.  
  302. Steffen Engel
  303.