home *** CD-ROM | disk | FTP | other *** search
/ Power-Programmierung / CD1.mdf / assemblr / library / lib4a86 / doc / queues.doc < prev    next >
Text File  |  1992-02-21  |  10KB  |  264 lines
  1.   ─────────────────────────────────────────────────────────────────────────────
  2.   Dokumentation zur Datei: QUEUES.INC
  3.  
  4.   ─────────────────────────────────────────────────────────────────────────────
  5.    
  6.     QUEUES.INC   - Routinen zur Verwaltung von meldungs- und stream-
  7.                    orientierten Queuen über Handles
  8.                    (für den Assembler A86)
  9.    
  10.                    (c) Bernd Schemmer 1992
  11.                    Letzter Update: 02.02.1992
  12.    
  13.    
  14.     ■ Beschreibung:
  15.     ---------------
  16.     Die hier aufgeführten Routinen ermöglichen es, stream- und meldungs-
  17.     orientierte Queuen über Handles analog zu Dateien zu verwalten.
  18.    
  19.     Die Routinen benötigen Routinen aus den Dateien SQUEUE.LIB, MQUEUE.LIB
  20.     und MEMORY.LIB.
  21.    
  22.    
  23.     ■ Routinen:
  24.     -----------
  25.     OpenQueue              - Öffnet eine Queue
  26.     CloseQueue             - Schließt eine Queue
  27.     ReadQueue              - Liest aus einer Queue
  28.     WriteQueue             - Schreibt in eine Queue
  29.     LookQueue              - Ermittelt die Daten der nächsten Meldung aus
  30.                              der Queue (nur für meldungsorientierte Queuen)
  31.     GetQueueData           - Ermittelt die globalen Daten einer Queue
  32.     GetMaxQueues           - Ermittelt die max. mögliche Anzahl Queuen
  33.                              und die Anzahl der schon eingerichteten Queuen
  34.     LockQueue              - Sperrt eine Queue
  35.     UnlockQueue            - Gibt eine Queue wieder frei
  36.     DeleteQueue            - Löscht eine Queue
  37.    
  38.    
  39.     Hinweis: Da nicht alle verwendeten Namen und Bezeichner dieser Datei
  40.              dokumentiert sind, sollten bei Nutzung dieser Routinen in
  41.              den anderen Quelltexten keine Namen oder Bezeichner, die
  42.              die Zeichenkette 'Queue' enthalten, verwendet werden.
  43.    
  44.    
  45.     ■ Konstanten
  46.     ------------
  47.     MaxQueueHandles  EQU 10xD    ; max. mögliche Anzahl an Queuen, kann
  48.                                  ; vom Programm umdefiniert werden!
  49.                                  ; (im Intervall von 1 bis 255)
  50.    
  51.    
  52.     ■ Fehlernummern der Routinen
  53.     ----------------------------
  54.    
  55.     Alle Fehlernummern der Routinen haben das Format 84xx, wobei xx die
  56.     Nummer des eigentlichen Fehlers ist. Neben diesen werden auch die
  57.     Fehlernummern der Routinen zur Verwaltung der Queuen (82xx und 83xx),
  58.     der Routinen zur Benutzung der DOS-Speicherverwaltung (81xx) und
  59.     DOS-Fehlernummern (00xx) zurückgeliefert.
  60.    
  61.     Name                   Nummer   Bedeutung
  62.     ----------------------------------------------------------------------
  63.                            000xxh ; DOS-Fehlernummer (normalerweise nur
  64.                                   ; 07h, 08h und 09h)
  65.    
  66.                            081xxh ; Fehlernummer einer Routine zur
  67.                                   ; Speicherverwaltung
  68.    
  69.                            082xxh ; Fehlernummer einer Routine zur
  70.                                   ; Bearbeitung von meldungsorientierten
  71.                                   ; Queuen
  72.    
  73.                            083xxh ; Fehlernummer einer Routine zur
  74.                                   ; Bearbeitung von streamorientierten
  75.                                   ; Queuen
  76.    
  77.     UnknownQSubfunction EQU 8401h ; Funktion wird von der Queue nicht
  78.                                   ; unterstützt
  79.    
  80.     InvalidQueueHandle EQU 08402h ; Das angegebene Handle bezieht sich
  81.                                   ; nicht auf eine offene Queue
  82.    
  83.     NoMoreQueueHandles EQU 08403h ; kein weiteres freies Handle mehr
  84.                                   ; vorhanden
  85.    
  86.    
  87.     ----------------------------
  88.     GetMaxQueues
  89.    
  90.     Funktion: Ermittelt die max. mögliche Anzahl Queuen und die Anzahl
  91.               der schon eingerichteten Queuen
  92.    
  93.     Eingabe:  -
  94.    
  95.     Ausgabe:  DX = max. mögliche Anzahl Queuen
  96.               CX = Anzahl schon eingerichteter Queuen
  97.               AL = Anzahl geöffneter meldungsorientierter Queuen
  98.               AH = Anzahl geöffneter streamorientierter Queuen
  99.    
  100.     ----------------------------
  101.     OpenQueue
  102.    
  103.     Funktion: Allociert den Speicher für eine neue Queue und öffnet sie
  104.    
  105.     Eingabe:  CX = Größe der Queue (incl. 16 Byte für den Header)
  106.               Bit 0 von AX = 0 ->> stream-orientierte Queue
  107.               Bit 0 von AX = 1 ->> meldungs-orientierte Queue
  108.    
  109.     Ausgabe:  CF = 0 ->> okay
  110.                          BX = Handle der Queue
  111.                          CX = freier Speicher in der Queue
  112.               CF = 1 ->> Fehler
  113.                          AX = Fehlernummer
  114.                          BX undefiniert
  115.    
  116.     Bes.:     Das Directionflag wird gelöscht.
  117.               Für jede Queue wird von DOS ein neuer Speicherblock
  118.               angefordert (via Funktion 48h des Interrupt 21h)
  119.    
  120.     ----------------------------
  121.     CloseQueue
  122.    
  123.     Funktion: Schliesst eine Queue und gibt den Speicher wieder frei
  124.    
  125.     Eingabe:  BX = Handle der Queue
  126.    
  127.     Ausgabe:  CF = 0 ->> okay
  128.               CF = 1 ->> Fehler
  129.                          AX = Fehlernummer
  130.    
  131.     Bes.:     Die Routine überprüft NICHT, ob in der Queue noch Meldungen
  132.               sind!
  133.    
  134.     ----------------------------
  135.     ReadQueue
  136.    
  137.     Funktion: Liest aus einer geöffneten Queue
  138.    
  139.     Eingabe:  BX = Handle der Queue
  140.               bei meldungsorientierten Queuen:
  141.                 DS:SI -> Puffer für die Meldung
  142.                 CX = Länge des Puffers
  143.               bei streamorientierten Queuen:
  144.                 DS:SI -> Puffer für die zu lesenden Bytes
  145.                 CX = Anzahl zu lesender Bytes
  146.    
  147.     Ausgabe:  CF = 0 ->> okay
  148.                          bei meldungsorientierten Queuen:
  149.                            Meldung steht im Puffer
  150.                            CX = Länge der Meldung
  151.                          bei streamorientierten Queuen:
  152.                            Die Bytes stehen im Puffer
  153.                            CX = Anzahl der gelesenen Bytes
  154.               CF = 1 ->> Fehler
  155.                          AX = Fehlernummer
  156.    
  157.    
  158.     Bes.:     Falls diese Routine mit CX = 0 für eine meldungsorientierte
  159.               Queue aufgerufen wird, verhält sie sich wie die Routine
  160.               'LookMQueue'.
  161.               Falls der Puffer bei DS:SI für die Meldung bei einer
  162.               meldungsorientierten Queue zu klein ist, wird die
  163.               Meldung NICHT aus der Queue entfernt.
  164.               Falls die Routine mit CX = 0 für eine streamorientierte
  165.               Queue aufgerufen wird, wird kein Byte gelesen und kein
  166.               Fehler generiert.
  167.               Das Directionflag wird gelöscht.
  168.    
  169.     ----------------------------
  170.     WriteQueue
  171.    
  172.     Funktion: Schreibt in eine geöffnete Queue
  173.    
  174.     Eingabe:  BX = Handle der Queue
  175.               bei meldungsorientierten Queuen:
  176.                 DS:SI -> zu schreibende Meldung
  177.                 CX = Länge der zu schreibenden Meldung
  178.               bei streamorientierten Queuen:
  179.                 DS:SI -> Speicherbereich mit den zu schreibenden Bytes
  180.                 CX = Anzahl der zu schreibenden Bytes
  181.    
  182.     Ausgabe:  CF = 0 ->> okay
  183.               CF = 1 ->> Fehler
  184.                          AX = Fehlernummer
  185.               bei meldungsorientierten Queuen:
  186.                 Falls AX = MQueueIsFull ist:
  187.                 CX = max. Länge einer weiteren Meldung für die Queue
  188.                      falls CX = - 1 ->> keine weitere Meldung möglich
  189.               bei streamorientierten Queuen:
  190.                 Falls AX = SQueueIsFull ist:
  191.                 CX = Anzahl freier Bytes in der Queue
  192.    
  193.     ----------------------------
  194.     LockQueue
  195.    
  196.     Funktion: Sperrt eine geöffnete Queue
  197.    
  198.     Eingabe:  BX = Handle der Queue
  199.    
  200.     Ausgabe:  CF = 0 ->> okay
  201.               CF = 1 ->> Fehler
  202.                          AX = Fehlernummer
  203.    
  204.     ----------------------------
  205.     UnLockQueue
  206.    
  207.     Funktion: Gibt eine gesperrte Queue wieder frei
  208.    
  209.     Eingabe:  BX = Handle der Queue
  210.    
  211.     Ausgabe:  CF = 0 ->> okay
  212.               CF = 1 ->> Fehler
  213.                          AX = Fehlernummer
  214.    
  215.     ----------------------------
  216.     DeleteQueue
  217.    
  218.     Funktion: Löscht den gesamten Inhalt einer geöffneten Queue
  219.    
  220.     Eingabe:  BX = Handle der Queue
  221.    
  222.     Ausgabe:  CF = 0 ->> okay
  223.               CF = 1 ->> Fehler
  224.                          AX = Fehlernummer
  225.    
  226.     ----------------------------
  227.     GetQueueData
  228.    
  229.     Funktion: Ermittelt die globalen Daten einer geöffneten Queue
  230.    
  231.     Eingabe:  BX = Handle der Queue
  232.    
  233.     Ausgabe:  CF = 0 ->> okay
  234.                          DI = Segment der Queue
  235.                          bei meldungsorientierten Queuen:
  236.                            CX = freier Speicher in der Queue
  237.                            DX = Größe der Queue
  238.                            AX = Anzahl der Meldungen in der Queue
  239.                          bei streamorientierten Queuen:
  240.                            CX = freier Speicher in der Queue
  241.                            DX = Größe der Queue
  242.                            AX = belegter Speicher in der Queue
  243.               CF = 1 ->> Fehler
  244.                          AX = Fehlernummer
  245.                          DI undefiniert
  246.    
  247.     ----------------------------
  248.     LookQueue
  249.    
  250.     Funktion: Ermittelt die Daten der nächsten Meldung einer geöffneten
  251.               Queue (nur bei meldungsorientierten Queuen möglich)
  252.    
  253.     Eingabe:  BX = Handle der Queue
  254.    
  255.     Ausgabe:  CF = 0 ->> okay
  256.                          bei meldungsorientierten Queuen:
  257.                            CX = Länge der nächsten Meldung
  258.                            und falls CX <> 0:
  259.                            AL = 1. Byte der Meldung
  260.    
  261.               CF = 1 ->> Fehler
  262.                          AX = Fehlernummer
  263.    
  264.