home *** CD-ROM | disk | FTP | other *** search
/ Power-Programmierung / CD1.mdf / assemblr / library / lib4a86 / doc / textio.doc < prev   
Text File  |  1992-02-22  |  16KB  |  404 lines
  1.   ─────────────────────────────────────────────────────────────────────────────
  2.   Dokumentation zur Datei: TEXTIO.INC
  3.  
  4.   ─────────────────────────────────────────────────────────────────────────────
  5.    
  6.     TEXTIO.INC   - Routinen zur sequentiellen gepufferten Bearbeitung
  7.                    von Textdateien
  8.                    (für den Assembler A86)
  9.    
  10.                    (c) Bernd Schemmer 1990 - 1992
  11.                    Letzter Update: 22.02.1992
  12.    
  13.     ■ Beschreibung:
  14.     ---------------
  15.     Die Routinen ermöglichen einem Programm die gepufferte Bearbeitung
  16.     von sequentiellen (Text-)Dateien.
  17.    
  18.     Alle Routinen erwarten in DS:BX einen Zeiger auf eine Datei-Tabelle
  19.     mit folgendem Aufbau:
  20.    
  21.            Offset | Länge   | Inhalt (alle Worte im INTEL-Format!)
  22.            -------+---------+--------------------------------------------
  23.              0    | 1  Wort | Datei-Handle
  24.     ┌─────>  2    | 1  Wort | Puffer-Größe in Byte
  25.     │             |         | (max. 0FFF0h = 65.520 dez. Bytes)
  26.     │        4    | 1  Wort | Puffer-Zeiger
  27.     │        6    | 1  Wort | Puffer-Ende
  28.     │  ┌──>  8    | 1  Wort | Offset des Puffers für die Dateibearbeitung
  29.     │  ├─>  10    | 1  Wort | Segment des Puffers für die Dateibearbeitung
  30.     │  │ ┌─>12    | 1  Byte | Datei-Status (-1 = geschlossen, 0 = lesen,
  31.     │  │ │        |         |                1 = schreiben)
  32.     │  │ │  13    | 1  Byte | Länge des Dateinamens (ohne NULL-Byte!) <───┐
  33.     │  │ │  14    | 65 Byte | Dateinamen incl. Pfad als String     <──────┤
  34.     │  │ │                                                                │
  35.     │  │ │                                                                │
  36.     │  │ │      Folgende Felder müssen initialisiert werden:              │
  37.     │  │ └───── Das Feld Datei-Status muß auf 0FFh (= -1) gesetzt werden. │
  38.     │  └─────── Das Feld für den Puffer-Offset, das Puffer-Segment, die   │
  39.     └────────── Puffer-Größe und die Felder für den Dateinamen müssen ────┘
  40.                 ebenfalls besetzt werden. Falls für die Größe des Puffers
  41.                 ein Wert größer als 0FFF0h Bytes angegeben wird, wird
  42.                 der Wert von den Routinen auf 0FFF0h gesetzt.
  43.                 Alle anderen Felder dürfen nicht initialisiert werden.
  44.                 Nach der Eröffnung einer Datei darf kein Feld der Struktur
  45.                 mehr verändert werden.
  46.    
  47.     Hinweis:    Die Tabelle kann hinter dem Dateinamen beliebig um private
  48.                 Felder erweitert werden (z.B. um ein Feld für den Modus der
  49.                 Datei oder das Attribut der Datei).
  50.                 Die Länge des Feldes für den Dateinamen kann auf die reale
  51.                 Länge des Dateinamens plus 1 beschränkt werden.
  52.    
  53.    
  54.     ■ Variablen:
  55.     ------------
  56.     UseControlZ
  57.    
  58.          Byte, falls diese Variable ungleich Null ist, arbeiten die
  59.          Routinen mit CTRL-Z als Dateiendezeichen. Steht die Variable
  60.          auf Null, so wird CTRL-Z nicht als Dateiendezeichen inter-
  61.          pretiert. Die Variable UseControlZ gilt jeweils GLOBAL für
  62.          alle über diese Routinen bearbeiteteten Dateien.
  63.          Sollen Dateien mit CTRL-Z-Markierung und ohne Markierung
  64.          gemischt verwendet werden, so muß zwischen den einzelnen
  65.          Dateioperationen jeweils der Inhalt von UseControlZ angepaßt
  66.          werden. Voreinstellung für UseControlZ ist 0FFh, d.h.
  67.          berücksichtige CTRL-Z.
  68.    
  69.     FileMode
  70.    
  71.          Byte, diese Variable enthält den Modus, der zum Öffnen einer
  72.          Datei verwendet wird (wobei nur die Bits 4 bis 7 berücksichtigt
  73.          werden). Voreinstellung für den FileModus ist 0; der Inhalt der
  74.          Variable ist nur bei der Eröffnung einer Datei von Bedeutung.
  75.          (RESET..., REWRITE... und APPEND..., Aufbau: siehe unten)
  76.    
  77.     CreateFileAttr
  78.    
  79.          Wort, Attribute für eine neu zu erstellende Datei (nur für
  80.          die Routinen CREATE... von Bedeutung) Voreinstellung für
  81.          das Attribut ist 0. Folgende Bits werden von den Routinen
  82.          ignoriert: Bit 3 (08h, Volume-Bit)
  83.                     Bit 4 (10h, Directory-Bit)
  84.                     und
  85.                     Bit 6 und 7 (40h und 80h, reservierte Bits)
  86.    
  87.          Hinweis:
  88.    
  89.          Das Attribut READ-ONLY ist erst bei einer weiteren Bearbeitung
  90.          der Datei wirksam. D.h. es kann durchaus eine Datei mit dem
  91.          Attribut READ-ONLY erstellt werden in die dann normal
  92.          geschrieben werden kann. Erst nach dem die Datei mindestens
  93.          einmal geschlossen wurde, ist das Attribut READ-ONLY wirksam.
  94.    
  95.    
  96.     ■ Routinen:
  97.     -----------
  98.     Hinweis: Alle Dateien, die zum Schreiben auf sind MÜSSEN vor dem
  99.              Programmende explizit über 'CloseFileBuffered' geschlossen
  100.              werden oder die Routine 'FlushFileBuffered' muß zum Leeren
  101.              des Puffers aufrufen werden, damit die Puffer in die Datei
  102.              geschrieben werden.
  103.    
  104.              Auch bei Auftritt eines Lese- oder Schreibfehler sollten
  105.              die Dateien noch geschlossen werden! Sonst erhält man über
  106.              kurz oder lang den Fehler 'Kein freies Handle mehr'.
  107.    
  108.     CreateFileBuffered    - Erstellt eine Datei (eine bestehende Datei
  109.                             wird überschrieben)
  110.     CreateNewFileBuffered - Erstellt eine neue Datei (eine bestehende
  111.                             Datei führt zu einem Fehler)
  112.     RewriteFileBuffered   - Öffnet eine Datei zum Schreiben
  113.     ResetFileBuffered     - Öffnet eine Datei zum Lesen
  114.     AppendFileBuffered    - Öffnet eine Datei zum Verlängern
  115.     WriteFileBuffered     - Schreibt in eine Datei
  116.     WritelnFileBuffered   - Schreibt in eine Datei (mit CR/LF)
  117.     ReadlnFileBuffered    - Liest aus einer Datei (bis zum nächsten CR/LF)
  118.     ReadFileBuffered      - Liest aus einer Datei (#n Zeichen)
  119.     FlushFileBuffer       - Schreibt den (internen) Puffer
  120.     CloseFileBufferd      - Schließt eine Datei
  121.    
  122.    
  123.     ■ Definition der Datei-Tabelle
  124.    
  125.        Dateitabelle STRUC [BX]
  126.        _Handle   dw ?                ; Handle der Datei
  127.        _Groesse  dw ?                ; Größe des Puffers
  128.        _Zeiger   dw ?                ; Puffer-Zeiger
  129.        _Ende     dw ?                ; Puffer-Ende
  130.        _Offset   dw ?                ; Offset des Puffers
  131.        _Segment  dw ?                ; Segment des Puffers
  132.        _status   db ?                ; Status der Datei
  133.        _Name     db ?                ; Name der Datei (als String)
  134.                  db 041h dup ?
  135.                  ENDS
  136.    
  137.    
  138.     ■ Bedeutung des Datei-Status-Feldes
  139.    
  140.     GESCHLOSSEN    EQU 0FFh
  141.     LESEN          EQU 000h
  142.     SCHREIBEN      EQU 001h
  143.    
  144.     ■ Fehlernummern
  145.    
  146.     EOF_KZ         EQU 0FFh     ; darf nicht 0 sein! (Lesen)
  147.     DISKVOLL       EQU 0FFh     ; darf nicht 0 sein! (Schreiben)
  148.     FALSCHER_MODE  EQU 0FEh     ; darf nicht 0 sein! (Öffnen, Erstellen,
  149.                                 ; Lesen, Schreiben und Schließen)
  150.    
  151.     CR             EQU 0Dh      ; ASCII-Code von RETURN
  152.     LF             EQU 0Ah      ; ASCII-Code von LINEFEED
  153.     CTRL_Z         EQU 1Ah      ; ASCII-Code von CTRL-Z
  154.    
  155.    
  156.    
  157.     ■ Aufbau des Modus-Bytes (= Variable FileMode):
  158.    
  159.       Bit    | Bedeutung     | Aufschlüsselung der Bits
  160.       -------+---------------+-------------------------------------------
  161.       0..3   | Zugriffscode  | 0000 nur Lesen         \  Diese Bits werden
  162.              |               | 0001 nur Schreiben      > von den Routinen
  163.              |               | 0010 Lesen + Schreiben /  gesetzt
  164.              |               |
  165.              |               | Die folgenden Bits werden aus der Variable
  166.              |               | FILEMODE ermittelt:
  167.              |               |
  168.       4..6   | Sharing-Code  | 000  Kompatibilitätsmodus
  169.              |               | 001  ablehnender Schreib/Lese-Modus
  170.              |               | 010  ablehnender Schreibmodus
  171.              |               | 011  ablehnender Lesemodus
  172.              |               | 100  nicht-ablehnender Modus
  173.              |               |
  174.       7      | Inherit-Bit   | 0    Zugriff für Unterprozesse erlaubt
  175.              |               | 1    Zugriff für Unterprozesse verboten
  176.    
  177.     ■ Voreinstellungen für die Modi:
  178.    
  179.     write_modus    EQU 002h       ; für RewriteFileBuffered
  180.                                   ; (für APPEND auch Lesen zulassen)
  181.     read_modus     EQU 000h       ; für ResetFileBuffered
  182.    
  183.    
  184.     ■ Aufbau des Attributes für die Erstellung einer neuen Datei
  185.       (= Variable CreateRFileAttr)
  186.    
  187.       Bit    | Bedeutung
  188.       -------+---------------
  189.        0     | Read-Only-Bit
  190.        1     | Hidden-Bit
  191.        2     | System-Bit
  192.        3     | Volume-Bit
  193.        4     | SubDir-Bit
  194.        5     | Archive-Bit
  195.        6     | reserviert, sollte 0 sein
  196.        7     | reserviert, sollte 0 sein
  197.       8-15   | reserviert, soltte 0 sein
  198.    
  199.    
  200.     ----------------------------
  201.     CreateFileBuffered
  202.    
  203.     Funktion:  Anlegen einer neuen Datei
  204.    
  205.     Eingabe:   DS:BX -> Datei-Tabelle
  206.    
  207.     Ausgabe:   CF = 0 ->> okay
  208.                           AX = Dateinummer
  209.                CF = 1 ->> Fehler
  210.                           AX = Fehlernummer
  211.                           AH = FALSCHER_MODE ->> Datei noch auf
  212.    
  213.     Bes.:      Die Variable CREATEFILEATTR enthält das Attribut für
  214.                die Datei.
  215.                Eine bestehende Datei wird überschrieben, d.h. gelöscht!
  216.    
  217.     ----------------------------
  218.     CreateNewFileBuffered
  219.    
  220.     Funktion:  Anlegen einer neuen Datei
  221.    
  222.     Eingabe:   DS:BX -> Datei-Tabelle
  223.    
  224.     Ausgabe:   CF = 0 ->> okay
  225.                           AX = Dateinummer
  226.                CF = 1 ->> Fehler
  227.                           AX = Fehlernummer
  228.                           AH = FALSCHER_MODE ->> Datei noch auf
  229.    
  230.     Bes.:      Die Variable CREATEFILEATTR enthält das Attribut für
  231.                die neue Datei.
  232.                Eine bestehende Datei wird nicht überschrieben, sondern
  233.                führt zu einem Fehler!
  234.    
  235.     ----------------------------
  236.     ResetFileBuffered
  237.    
  238.     Funktion:  Öffnen einer bestehenden Datei zum Lesen
  239.    
  240.     Eingabe:   DS:BX -> Datei-Tabelle
  241.    
  242.     Ausgabe:   CF = 0 ->> okay
  243.                           AX = Dateinummer
  244.                CF = 1 ->> Fehler
  245.                           AX = Fehlernummer
  246.                           AH = FALSCHER_MODE ->> Datei noch auf
  247.    
  248.     Bes.:      Die Variable FILEMODE enthält den Modus für die
  249.                Eröffnung der Datei.
  250.    
  251.     ----------------------------
  252.     RewriteFileBuffered
  253.    
  254.     Funktion:  Öffnen einer bestehenden Datei zum Schreiben
  255.    
  256.     Eingabe:   DS:BX -> Datei-Tabelle
  257.    
  258.     Ausgabe:   CF = 0 ->> okay
  259.                           AX = Dateinummer
  260.                CF = 1 ->> Fehler
  261.                           AX = Fehlernummer
  262.                           AH = FALSCHER_MODE ->> Datei noch auf
  263.    
  264.     Bes.:      Die Variable FILEMODE enthält den Modus für die
  265.                Eröffnung der Datei
  266.    
  267.     ----------------------------
  268.     AppendFileBuffered
  269.    
  270.     Funktion:  Öffnen einer bestehenden Datei zum Anfügen am Ende
  271.    
  272.     Eingabe:   DS:BX -> Datei-Tabelle
  273.    
  274.     Ausgabe:   CF = 0 ->> okay
  275.                           AX = Dateinummer
  276.                CF = 1 ->> Fehler
  277.                           AX = Fehlernummer
  278.                           AH = FALSCHER_MODE ->> Datei noch auf
  279.    
  280.     Bes.:      Falls die Variable UseControlZ ungleich 0 ist,
  281.                wird ein CTRL-Z am Dateiende der bestehenden Datei
  282.                überschrieben.
  283.                Die Variable FILEMODE enthält den Modus für die
  284.                Eröffnung der Datei.
  285.    
  286.     ----------------------------
  287.     ReadFileBuffered
  288.    
  289.     Funktion:  Lesen einer bestimmten Anzahl Zeichen aus einer Datei
  290.    
  291.     Eingabe:   ES:DI -> Puffer für die Zeichen
  292.                DS:BX -> Datei-Tabelle
  293.                CX = Anzahl max. zu lesender Zeichen
  294.                     mit CX <= 255
  295.    
  296.     Ausgabe:   CF = 0 ->> okay
  297.                           der Puffer ist mit dem gelesen String
  298.                           (incl. Längenbyte) gefüllt.
  299.                CF = 1 ->> Fehler
  300.                           AX = Fehlernummer
  301.                           AH = FALSCHER_MODE
  302.                                ->> Datei nicht zum Lesen auf
  303.                           AH = EOF_KZ ->> EOF
  304.    
  305.     Bes.:      Falls die Variable UseControlZ ungleich 0 ist, wird
  306.                CTRL-Z als Dateiende interpretiert.
  307.                Alle anderen ASCII-Steuerzeichen (auch CR und LF!) werden
  308.                nicht interpretiert.
  309.    
  310.     ----------------------------
  311.     ReadlnFileBuffered
  312.    
  313.     Funktion:  Lesen aus der Datei bis zum  nächsten Zeilen- bzw.
  314.                Dateiende
  315.                Als Markierung für das Zeilenende werden folgende
  316.                Zeichenfolgen erkannt:
  317.                  CR
  318.                  CR und LF
  319.                  LF und CR
  320.    
  321.     Eingabe:   ES:DI -> Puffer für den String
  322.                DS:BX -> Datei-Tabelle
  323.    
  324.     Ausgabe:   CF = 0 ->> okay
  325.                           Der Puffer ist mit dem gelesenen String
  326.                           (incl. Längenbyte) gefüllt.
  327.                CF = 1 ->> Fehler
  328.                           AX = Fehlernummer
  329.                           AH = FALSCHER_MODE
  330.                                ->> Datei nicht zum Lesen auf
  331.                           AH = EOF_KZ ->> EOF
  332.    
  333.     Bes.:      Falls die Variable UseControlZ ungleich 0 ist, wird
  334.                CTRL-Z als Dateiende interpretiert.
  335.                Alle anderen ASCII-Steuerzeichen (außer CR und LF)
  336.                werden nicht interpretiert.
  337.    
  338.     ----------------------------
  339.     WriteFileBuffered
  340.    
  341.     Funktion:  Sequentielles Schreiben in eine Datei
  342.    
  343.     Eingabe:   DS:SI -> Zu schreibender String
  344.                DS:BX -> Datei-Tabelle
  345.    
  346.     Ausgabe:   CF = 0 ->> okay
  347.                           String geschrieben
  348.                CF = 1 ->> Fehler
  349.                           AX = Fehlernummer
  350.                           AH = FALSCHER_MODE ->> Datei nicht zum
  351.                                                  Schreiben auf
  352.                           AH = DISK_VOLL ->> Diskette voll
  353.    
  354.     ----------------------------
  355.     WritelnFileBuffered
  356.    
  357.     Funktion:  Sequentielles Schreiben in eine Datei mit CR/LF
  358.    
  359.     Eingabe:   DS:SI -> String
  360.                DS:BX -> Datei-Tabelle
  361.    
  362.     Ausgabe:   CF = 0 ->> okay
  363.                           String geschrieben
  364.                CF = 1 ->> Fehler
  365.                           AX = Fehlernummer
  366.                           AH = FALSCHER_MODE ->> Datei nicht zum
  367.                                                  Schreiben auf
  368.                           AH = DISK_VOLL ->> Diskette voll
  369.    
  370.     ----------------------------
  371.     FlushFileBuffer
  372.    
  373.     Funktion:  Schreibt den Puffer
  374.    
  375.     Eingabe:   DS:BX -> Datei-Tabelle
  376.    
  377.     Ausgabe:   CF = 0 ->> okay
  378.                           Puffer geschrieben
  379.                CF = 1 ->> Fehler
  380.                           AH = FALSCHER_MODE ->> Datei nicht zum
  381.                                                  Schreiben auf
  382.                           AH = DISK_VOLL ->> Disk ist voll
  383.    
  384.     Bes.:      Ab der DOS-Version 3.30 werden auch die internen DOS-Puffer
  385.                über die Funktion 68h des Interrupt 21h geschrieben.
  386.    
  387.     ----------------------------
  388.     CloseFileBufferd
  389.    
  390.     Funktion:  Leeren des Puffers (bei Eröffnung zum SCHREIBEN) und
  391.                Schliessen der Datei
  392.    
  393.     Eingabe:   DS:BX -> Datei-Tabelle
  394.    
  395.     Ausgabe:   CF = 0 ->> okay
  396.                CF = 1 ->> Fehler
  397.                           AX = Fehlernummer
  398.                           AH = DISKVOLL ->> Diskette ist voll
  399.    
  400.     Bes.:      Falls UseControlZ ungleich 0 ist, so wird vor dem
  401.                Schliessen der Datei noch ein CTRL-Z in diese
  402.                geschrieben.
  403.    
  404.