home *** CD-ROM | disk | FTP | other *** search
/ Power-Programmierung / CD1.mdf / assemblr / library / lib4a86 / doc / squeue.doc < prev    next >
Text File  |  1992-02-11  |  8KB  |  215 lines
  1.   ─────────────────────────────────────────────────────────────────────────────
  2.   Dokumentation zur Datei: SQUEUE.INC
  3.  
  4.   ─────────────────────────────────────────────────────────────────────────────
  5.    
  6.     SQUEUE.INC   - Routinen zur Verwaltung einer stream-orientierten Queue
  7.                    (für den Assembler A86)
  8.    
  9.                    (c) Bernd Schemmer 1992
  10.                    Letzter Update: 02.02.1992
  11.    
  12.    
  13.     ■ Beschreibung:
  14.     ---------------
  15.     SQUEUE.INC stellt Routinen zur Verwaltung einer stream-orientierten
  16.     Queue zur Verfügung. Eine Queue (oder auf deutsch: Schlange) ist eine
  17.     nach dem FIFO-Prinzip (First in, First out) organisierte Datenstruktur
  18.     zur Speicherung von Daten.
  19.    
  20.     Die Größe einer Queue, die durch diese Routinen verwaltet werden soll,
  21.     muß zwischen 256 und 65.535 Byte liegen.
  22.    
  23.     Jede Queue beginnt immer mit einem 16 Byte großem Header auf einer
  24.     Segment-Grenze.
  25.    
  26.     Jede Queue ist durch einen Semaphor vor gleichzeitiger Bearbeitung
  27.     durch mehrere Prozesse geschützt, wodurch die Queue auch durch
  28.     mehrere verschiedene Prozesse gefüllt und geleert werden kann.
  29.    
  30.     Es ist auch möglich, eine Queue in eine Datei zu sichern und später
  31.     wieder zu laden, da die Routinen nur mit relativen Offsets arbeiten.
  32.     Es muß aber immer die gesamte Queue gesichert und geladen werden.
  33.    
  34.     Da alle Variablen zur Verwaltung der Queue im Segment der Queue
  35.     angelegt werden, können die Routinen auch mit mehreren Queuen
  36.     gleichzeitig arbeiten.
  37.    
  38.    
  39.     ■ Variablen:
  40.     ------------
  41.     SQueueSeg             - Word, Segment der aktuellen Queue
  42.    
  43.          Alle Routinen (außer InitSQueue) definieren einen zusätzlichen
  44.          Einsprungpunkt 'name_A'. (z.B. für 'WriteSQueue' ist dies
  45.          'WriteSQueue_A'). Falls die Routinen über diesen Einsprung-
  46.          punkt aufgerufen werden, arbeiten sie mit der Queue, deren
  47.          Segment in dieser Variable gespeichert ist. (Der Wert des
  48.          Registers ES beim Aufruf ist in diesen Fall ohne Bedeutung,
  49.          das Register ES wird aber NICHT gesichert.) Die Variable muß
  50.          in diesem Fall vorher auf einen korrekten Wert gesetzt worden
  51.          sein! (z.B. durch den Aufruf von 'InitSQueue' oder durch
  52.          direktes Setzen)
  53.          Falls die Routinen über den normalen Einsprungpunkt aufgerufen
  54.          werden, wird diese Variable weder genutzt noch verändert.
  55.    
  56.     SQueueSeg:[SQueueUserData1] - Word, für Benutzerzwecke reserviert
  57.     SQueueSeg:[SQueueUserData2] - Word, für Benutzerzwecke reserviert
  58.    
  59.          An den Offsets SQueueUserData1 und SQueueUserData2 im Header
  60.          der Queue sind jeweils 2 Byte (= 1 Wort) für Daten des Programms
  61.          reserviert. Diese beiden Wörter werden von den Routinen zur
  62.          Verwaltung der Queue weder gelesen noch verändert (also auch
  63.          nicht mit einem bestimmten Wert initialisiert).
  64.          (SQueueUserData1 und SQueueUserData2 sind über 'dw' definiert)
  65.    
  66.    
  67.     Alle anderen Variablen zur Verwaltung der Queue werden im Speicher-
  68.     bereich für die Queue angelegt und sollten von anderen Routinen
  69.     weder gelesen noch verändert werden.
  70.    
  71.    
  72.     ■ Routinen:
  73.     -----------
  74.     InitSQueue             - Initialisert (d.h. löscht) die Queue
  75.     LockSQueue             - Sperrt eine Queue
  76.     UnLockSQueue           - Gibt eine Queue wieder frei
  77.     DeleteSQueue           - Löscht die gesamte Queue
  78.     WriteSQueue            - Schreibt n Byte in die Queue
  79.     ReadSQueue             - Liest die nächsten n Byte aus der Queue
  80.     GetSQueueStatistik     - Ermittelt die Daten der Queue
  81.    
  82.     Hinweis: Da nicht alle internen Bezeichner dieser Routinen dokumentiert
  83.              sind, sollte in einem Programm, das diese Routinen nutzt, kein
  84.              Bezeichner mit der Zeichenfolge 'SQueue' verwendet werden.
  85.    
  86.    
  87.     ■ Fehlernummern der Routinen
  88.     ----------------------------
  89.    
  90.     Alle Fehlernummern der Routinen haben das Format 83xx, wobei xx die
  91.     Nummer des eigentlichen Fehlers ist.
  92.    
  93.     Name                   Nummer   Bedeutung
  94.     ---------------------------------------------------------------------
  95.     SQueueIsEmpty      EQU 08301h ; Die Queue ist leer
  96.    
  97.     SQueueIsFull       EQU 08302h ; Es ist nicht mehr genügend freier
  98.                                   ; Speicher zur Aufnahme der Bytes in
  99.                                   ; der Queue frei
  100.    
  101.     SQueueLengthError  EQU 08303h ; falsche Größe für die Queue angegeben
  102.    
  103.     SQueueAktivError   EQU 083FFh ; gleichzeigtiger Zugriff von mehreren
  104.                                   ; Prozessen auf eine Queue nicht möglich
  105.    
  106.    
  107.     ----------------------------
  108.     InitSQueue
  109.    
  110.     Funktion: Initialisiert die Queue
  111.    
  112.     Eingabe:  ES = Segment für die Queue
  113.                    Die Queue beginnt immer am Offset 0
  114.               CX = Größe des Speicherbereichs in Byte für die Queue
  115.                    Es muß gelten: 256 < CX < 65.535
  116.    
  117.     Ausgabe:  CF = 0 ->> okay
  118.                          CX = freier Speicher in der Queue
  119.               CF = 1 ->> Fehler
  120.                          AX = Fehlernummer
  121.                          Die Queue wurde NICHT eingerichtet.
  122.    
  123.     Bes.:     Das Segment der Queue wird, falls kein Fehler auftritt, in
  124.               der Variablen SQueueSeg gespeichert.
  125.               Der Wert des Semaphors der Queue wird NICHT berücksichtigt!
  126.    
  127.     ----------------------------
  128.     DeleteSQueue
  129.    
  130.     Funktion: Löscht die gesamte Queue
  131.    
  132.     Eingabe:  ES = Segment der Queue
  133.    
  134.     Ausgabe:  CF = 0 ->> okay
  135.                          CX = freier Speicher in der Queue
  136.               CF = 1 ->> Fehler
  137.                          AX = Fehlernummer
  138.    
  139.     ----------------------------
  140.     LockSQueue
  141.    
  142.     Funktion: Sperrt eine Queue
  143.    
  144.     Eingabe:  ES = Segment der Queue
  145.    
  146.     Ausgabe:  CF = 0 ->> okay
  147.               CF = 1 ->> Fehler
  148.                          AX = Fehlernummer
  149.    
  150.     ----------------------------
  151.     UnLockSQueue
  152.    
  153.     Funktion: Gibt eine Queue wieder frei
  154.    
  155.     Eingabe:  ES = Segment der Queue
  156.    
  157.     Ausgabe:  CF = 0 ->> okay
  158.               CF = 1 ->> Fehler
  159.                          AX = Fehlernummer
  160.    
  161.     Bes.:     Der Wert des Semaphors der Queue wird NICHT berücksichtigt!
  162.    
  163.     ----------------------------
  164.     GetSQueueStatistik
  165.    
  166.     Funktion: Ermittelt die statistischen Daten der Queue
  167.    
  168.     Eingabe:  ES = Segment der Queue
  169.    
  170.     Ausgabe:  CF = 0 ->> okay
  171.                          AX = belegter Speicher in der Queue
  172.                          CX = freier Speicher in der Queue
  173.                          DX = Größe der Queue
  174.               CF = 1 ->> Fehler
  175.                          AX = Fehlernummer
  176.    
  177.     ----------------------------
  178.     WriteSQueue
  179.    
  180.     Funktion: Schreiben von n Bytes in die Queue
  181.    
  182.     Eingabe:  ES = Segment der Queue
  183.               CX = Anzahl der zu schreibenden Bytes
  184.               DS:SI -> zu schreibende Bytes
  185.    
  186.     Ausgabe:  CF = 0 ->> okay
  187.               CF = 1 ->> Fehler
  188.                          AX = Fehlernummer
  189.                          und falls AX = SQueueIsFull ist:
  190.                          CX = Anzahl freier Bytes in der Queue
  191.    
  192.     Bes.:     Das Directionflag wird gelöscht.
  193.               Im Falle eines Fehlers werden KEINE Bytes geschrieben.
  194.    
  195.     ----------------------------
  196.     ReadSQueue
  197.    
  198.     Funktion: Liest die nächsten n Bytes aus der Queue
  199.    
  200.     Eingabe:  ES = Segment der Queue
  201.               CX = Anzahl der zu lesenden Bytes
  202.               DS:SI -> Puffer für die Bytes
  203.    
  204.     Ausgabe:  CF = 0 ->> okay
  205.                          Bytes stehen im Puffer bei DS:SI
  206.                          CX = Anzahl der übertragenen Bytes
  207.                               (1 <= CX <= n, mit n = angeforderte Bytes)
  208.               CF = 1 ->> Fehler
  209.                          AX = Fehlernummer
  210.    
  211.     Bes.:     Das Directionflag wird gelöscht.
  212.               Falls die Routine mit CX = 0 aufgerufen wird, wird sie
  213.               sofort beendet.
  214.    
  215.