home *** CD-ROM | disk | FTP | other *** search
/ Power-Programmierung / CD1.mdf / assemblr / library / lib4a86 / doc / env.doc < prev    next >
Text File  |  1992-02-13  |  14KB  |  357 lines
  1.   ─────────────────────────────────────────────────────────────────────────────
  2.   Dokumentation zur Datei: ENV.INC
  3.  
  4.   ─────────────────────────────────────────────────────────────────────────────
  5.    
  6.     ENV.INC      - Routinen zur Bearbeitung des Environments
  7.                    (für den Assembler A86)
  8.    
  9.                    (c) Bernd Schemmer 1990 - 1992
  10.                    Letzter Update: 13.02.1992
  11.    
  12.     ■ Hinweis:
  13.     ----------
  14.     Alle Strings besitzen einen Längenzähler (erstes Byte) Deshalb kann
  15.     ein Eintrag im Environment (Name, Inhalt und Gleicheitszeichen) max.
  16.     255 Zeichen lang sein.
  17.    
  18.     Alle Routinen arbeiten auf dem aktuellen Environment. Das aktuelle
  19.     Environment kann das lokale Environment (= Environment dieses
  20.     Programms), das Environment des aufrufenden Programmes oder das
  21.     Master-Environment des Kommando-Interpreters (normalerweise der
  22.     COMMAND.COM, bei 4DOS eingeschränkt, siehe Dokumentation zu 4DOS)
  23.     sein. Zum Umschalten des aktuellen Environments dient die Routine
  24.     'UseOtherEnv'. Voreingestellt für das aktuelle Environment ist das
  25.     lokale Environment.
  26.    
  27.     Falls eines der Environmente über andere Routinen als die in dieser
  28.     Datei zusammengestellten verändert wird, muß die Routine 'InitEnv-
  29.     Routines' vor der weiteren Benutzung der Routinen aufgerufen werden!
  30.    
  31.     Zur Initialisierung sollte zu Programmbeginn einmal die Routine
  32.     'InitEnvRoutines' aufgerufen werden.
  33.    
  34.     Die Routinen zur Bearbeitung des Environments des aufrufenden
  35.     Programms benutzen das undokumentierte Feld mit dem Offset 16h im
  36.     PSP (= PSP-Segment des aufrufenden Programmes), die Routinen zur
  37.     Bearbeitung des Master-Envrionments benutzen die undokumentierte
  38.     Funktion 52h des Interrupt 21h, den undokumentierten DOS-Info-Block
  39.     und die undokumentierten MCBs.
  40.    
  41.     Die Routinen können nur bei DOS-Version ab 3.0 eingesetzt werden
  42.     (muß von der aufrufenden Routine überprüft werden!).
  43.    
  44.     Die Routinen gehen davon aus, daß die Master-Kopie des COMMAND.COM
  45.     den zweiten Speicherblock belegt. Falls dem nicht so ist, sollte
  46.     ein Programm zuerst die Routine 'InitEnvRoutines' aufrufen und dann
  47.     die Variable 'CommandEnvSeg' direkt auf den korrekten Wert setzen.
  48.    
  49.     Falls die Routinen mit einen Fehler enden, bedeutet dies normaler-
  50.     weise (d.h. es ist nichts anderes angegeben), daß das aktuelle
  51.     Environment nicht nutzbar ist.
  52.    
  53.    
  54.     ■ Variablen:
  55.     ------------
  56.     LokalEnvSeg           - Segment des lokalen Environments
  57.                              Sonderfall:  0 - Segment noch nicht ermittelt
  58.                                          -1 - Segment wurde freigegeben
  59.     CallerEnvSeg          - Segment des Environments des aufrufenden
  60.                             Prozesses
  61.                              Sonderfall:  0 - Segment noch nicht ermittelt
  62.                                          -1 - Segment nicht ermittelbar
  63.     CommandEnvSeg         - Segment des Master-Environments des COMMAND.COM
  64.                              Sonderfall:  0 - Segment noch nicht ermittelt
  65.                                          -1 - Segment nicht ermittelbar
  66.    
  67.    
  68.     ■ Routinen:
  69.     -----------
  70.     GetProgName           - Ermittelt den Namen des Programms aus
  71.                             dem Environment
  72.     EnvCount              - Ermittelt die Anzahl der Einträge im
  73.                             Environment
  74.     GetEnvData            - Ermittelt die Speicherdaten des aktuellen
  75.                             Environments
  76.     EnvStr                - Ermittelt einen best. Environment-Eintrag
  77.     EnvParse              - Splittet einen Environment-Eintrag in Name
  78.                             und Inhalt
  79.     SearchEnvStr          - Ermittelt den Inhalt einer vorgegebenen
  80.                             Environment-Variable
  81.     FreeLokalEnv          - Gibt das lokale Environment frei
  82.     UseOtherEnv           - Wechselt das aktuelle Environment
  83.     UsedEnvSeg?           - Ermittelt des aktuelle Environment
  84.     GetCallerName         - Ermittelt den Namen des aufrufenden Programmes
  85.     SetEnvVar             - Erstellt, löscht oder ändert eine Environment-
  86.                             Variable
  87.     InitEnvRoutine        - Initialisiert die Routinen und Daten
  88.    
  89.     und falls nötig:
  90.     Upcase                - Konvertiert ein Zeichen in Großbuchstaben
  91.     ParseStr              - Splittet einen String ab einen vorgegebenen
  92.                             Zeichen
  93.     DOSStrToStr           - Konvertiert einen DOS-String ins Stringformat
  94.    
  95.    
  96.    
  97.     ■ Konstanten:
  98.     -------------
  99.     UseLokalEnv      EQU 0        ; Byte, EQU-Anweisungen für das akt.
  100.     UseCallerEnv     EQU 1        ; Environment
  101.     UseCOMMANDEnv    EQU 2
  102.    
  103.    
  104.     ----------------------------
  105.     SetEnvVar
  106.    
  107.     Funktion:  Setzen, Ändern oder Löschen einer Variable im aktuellen
  108.                Environment
  109.    
  110.     Eingabe:   DS:SI -> Name der Variable als String
  111.                         Das Zeichen '=' und Nullbytes dürfen im Namen
  112.                         nicht vorkommen.
  113.                ES:DI -> neuer Inhalt der Variablen als String
  114.                         Im String darf kein Nullbyte vorkommen.
  115.                         (leerer String ->> löschen der Variable)
  116.    
  117.     Ausgabe:   Der Name wird in Großbuchstaben konvertiert.
  118.                CF = 0 ->> okay
  119.                           und bei Löschen:
  120.                           ZF = 1 ->> Variable ist nicht vorhanden
  121.                           ZF = 0 ->> Variable gelöscht
  122.    
  123.                CF = 1 ->> Fehler, Grund:
  124.                           bei Setzen/Ändern/Löschen:
  125.                              akt. Environment nicht mehr gültig
  126.                              oder
  127.                              '=' oder Nullbyte im Namen enthalten
  128.                              oder
  129.                              Nullbyte im Inhalt enthalten
  130.                              oder
  131.                              Leerer String als Namen angegeben
  132.                           oder bei Setzen/Ändern:
  133.                              Environmentüberlauf
  134.    
  135.     Bes.:      Mit dieser Routine können Environment-Einträge mit max.
  136.                501 Zeichen Länge erstellt werden (max. 255 Zeichen für
  137.                den Namen, max. 255 Zeichen für den Inhalt und 1 Zeichen
  138.                für den Trenner '=').
  139.                Einträge länger als 255 Zeichen (Name, Inhalt und Gleich-
  140.                heitszeichen) können aber von den restlichen Routinen
  141.                NICHT bearbeitet werden!
  142.    
  143.                Bei einem Überlauf des Environments wird eine existierende
  144.                Variable auf jeden Fall gelöscht. Soll dies verhindert
  145.                werden, muß vorher über die Routine 'GetEnvData' die Anzahl
  146.                der freien Bytes im aktuellen Environment und über 'GetEnvVar'
  147.                die Länge der evtl. schon bestehenden Variable überprüft
  148.                werden. Die Länge des neuen Eintrags kann folgendermaßen
  149.                berechnet werden:
  150.    
  151.                      Länge des Namens
  152.                    + Länge des Inhaltes
  153.                    + 1 (für das Zeichen '=')
  154.                und, falls schon Variablen im Environment vorhanden
  155.                sind:
  156.                    + 1 (für das Endekennzeichen des Eintrages)
  157.    
  158.     ----------------------------
  159.     SearchEnvStr
  160.    
  161.     Funktion:  Ermittelt den Inhalt einer durch den Namen angegebenen
  162.                Environment-Variable aus dem aktuellen Environment.
  163.    
  164.     Eingabe:   DS:SI -> Name der Variablen als String
  165.                ES:DI -> Puffer für den Inhalt
  166.    
  167.     Ausgabe:   CF = 0 ->> Gefunden
  168.                           ES:DI -> Inhalt als String
  169.                CF = 1 ->> nicht gefunden
  170.                           ES:DI -> leerer String
  171.    
  172.     ACHTUNG:   Die Routine benötigt ca. 540 Byte auf dem Stack
  173.                (u.a. für lokale Variable)
  174.    
  175.                Für den String und den Puffer kann die gleiche Variable
  176.                verwendet werden (der Name wird dann aber in jeden Fall
  177.                überschrieben oder gelöscht)
  178.    
  179.     ----------------------------
  180.     EnvParse
  181.    
  182.     Funktion:  Splittet einen Eintrag aus dem Environment in den Namen
  183.                und den Inhalt (das '=' wird verworfen)
  184.    
  185.     Eingabe:   DS:SI -> Namen und Inhalt der Variable als String
  186.                ES:DI -> Puffer für den Inhalt
  187.     
  188.     Ausgabe:   CF = 0 ->> Parsen ok
  189.                           DS:SI -> Name als String
  190.                           ES:DI -> Inhalt als String
  191.                CF = 1 ->> Parsen fehlerhaft (->> kein Gleichheitszeichen
  192.                           gefunden) Der Name ist unverändert und der Puffer
  193.                           ist gelöscht.
  194.    
  195.     Bes.:      Falls der Quellstring mehr als ein Gleichheitszeichen enthält,
  196.                wird nur das erste berücksichtigt.
  197.    
  198.                Die beiden Strings müssen verschieden sein.
  199.    
  200.     ----------------------------
  201.     EnvStr
  202.    
  203.     Funktion:  Ermittelt den Eintrag mit der Nummer aus AL aus dem
  204.                Environment
  205.    
  206.     Eingabe:   AL = Nummer des Eintrages (Zählung beginnt bei 1)
  207.                ES:DI -> Puffer für den Eintrag
  208.    
  209.     Ausgabe:   CF = 0 ->> okay
  210.                           ES:DI -> String im Puffer falls Eintrag
  211.                                    vorhanden oder leerer String im
  212.                                    Puffer falls Eintrag nicht vorhanden
  213.                CF = 1 ->> Fehler
  214.                           ES:DI -> leerer String
  215.    
  216.     Bes.:      Falls als Nummer 0 angegeben wird, wird der erste Eintrag
  217.                zurückgegeben.
  218.    
  219.                Falls der Eintrag länger als 255 Zeichen ist, werden nur
  220.                die ersten 255 Zeichen übernommen.
  221.    
  222.     ----------------------------
  223.     GetEnvData
  224.    
  225.     Funktion:  Ermittelt die Daten des akt. Envrionments
  226.    
  227.     Ausgabe:   CF = 0 ->> okay
  228.                           AX = Länge des Environments in Byte
  229.                           BX = Anzahl der belegten Bytes
  230.                           CX = Anzahl der freien Bytes
  231.                CF = 1 ->> Fehler
  232.    
  233.     ----------------------------
  234.     EnvCount
  235.    
  236.     Funktion:  Ermittelt die Anzahl der Einträge im akt. Environment
  237.    
  238.     Ausgabe:   CF = 0 ->> okay
  239.                           AX = Anzahl der Einträge
  240.                CF = 1 ->> Fehler
  241.    
  242.     ----------------------------
  243.     UsedEnvSeg?
  244.    
  245.     Funktion:  Ermittelt das aktuelle Environment-Segment
  246.    
  247.     Ausgabe:   AL = 0 ->> lokales Environment
  248.                AL = 1 ->> Caller-Environment
  249.                AL = 2 ->> Master-Environment
  250.                und
  251.                CF = 0 ->> akt. Environment noch gültig
  252.                CF = 1 ->> akt. Environment ungültig
  253.    
  254.     ----------------------------
  255.     UseOtherEnv
  256.    
  257.     Funktion:  Umsetzen der Routinen auf ein best. Environment
  258.    
  259.     Eingabe:   AL = 0 ->> benutze lokales Environment
  260.                AL = 1 ->> benutze Caller-Environment
  261.                AL = 2 ->> benutze Master-Environment
  262.                sonst Fehler
  263.    
  264.     Ausgabe:   CF = 0 ->> okay
  265.                CF = 1 ->> Fehler, angegebenes Environment nicht
  266.                           gültig oder falsche Nummer angegeben
  267.                           akt. Environment wurde nicht geändert
  268.    
  269.     ----------------------------
  270.     FreeLokalEnv
  271.    
  272.     Funktion:  Lokales Environment freigeben
  273.    
  274.     Ausgabe:   CF = 0 ->> okay
  275.                CF = 1 ->> Fehler
  276.                           AX = DOS-Fehlernummer
  277.                           oder
  278.                           AX = 0FFFFh falls das Segment schon freigegeben
  279.                                wurde
  280.     ----------------------------
  281.     Upcase
  282.    
  283.     Funktion:   Konvertierung des Zeichens in AL in einen Großbuchstaben
  284.                 Berücksichtigt die Umlaute ä, ö und ü (ß bleibt ß)
  285.    
  286.     Eingbabe:   AL = zu konvertierendes Zeichen
  287.    
  288.     Ausgabe:    AL = konvertiertes Zeichen 
  289.    
  290.     ----------------------------
  291.     ParseStr
  292.    
  293.     Funktion:  Trennt einen String ab einem vorgegebenen Zeichen
  294.    
  295.     Eingabe:   DS:SI -> Quellstring
  296.                ES:DI -> Puffer für den Zielstring.
  297.                AL = Trennzeichen (wird in keinen Teil übernommen!)
  298.    
  299.     Ausgabe:   DS:SI -> vorderer Teil
  300.                ES:DI -> hinterer Teil
  301.    
  302.     Bes.:
  303.    
  304.     Zielstring muß ungleich Quellstring sein, bei mehreren Vor-
  305.     kommen des Trennzeichens wird beim ersten Vorkommen getrennt
  306.    
  307.     ----------------------------
  308.     DOSStrToStr
  309.    
  310.     Funktion:  Konvertierung eines DOS-Strings ins String-Format
  311.                (mit Zähler, ohne das Zeichen '$' bzw. ein 0-Byte
  312.                am Ende)
  313.    
  314.     Eingabe:   DS:SI -> Quellstring
  315.                ES:DI -> Zielstring (wird auf max. 255 Byte gekürzt)
  316.                AL = Ende-Kennzeichen (0-Byte oder '$')
  317.    
  318.     Bes.:      Zielstring gleich Quellstring ist nicht erlaubt.
  319.    
  320.                Falls der Quellstring mehr als 255 Zeichen hat, werden
  321.                nur die ersten 255 Zeichen übernommen.
  322.    
  323.     ----------------------------
  324.     GetCallerName
  325.    
  326.     Funktion:  Ermittelt den Namen des aufrufenden Programmes
  327.    
  328.     Eingabe:   ES:DI -> Puffer für den Namen als String
  329.    
  330.     Ausgabe:   CF = 0 ->> okay
  331.                           ZF = 0 ->> ES:DI -> Name
  332.                           ZF = 1 ->> ES:DI -> leerer String, Programm wurde
  333.                                                vom COMMAND.COM aufgerufen.
  334.                CF = 1 ->> Fehler
  335.    
  336.     ----------------------------
  337.     GetProgName
  338.    
  339.     Funktion:  Ermittelt den Programm-Namen aus dem Environment
  340.    
  341.     Eingabe:   ES:DI = Puffer für den Namen als String
  342.    
  343.     Ausgabe:   CF = 0 ->> okay
  344.                           ZF = 0 ->> ES:DI -> Name des Programms
  345.                           ZF = 1 ->> ES:DI -> leerer String, Name konnte
  346.                                               nicht ermittelt werden
  347.                CF = 1 ->> Fehler
  348.    
  349.     ----------------------------
  350.     InitEnvRoutines
  351.    
  352.     Funktion:  Initialisieren der Variablen
  353.                ACHTUNG: Nach Aufruf dieser Routine sind alle Daten auf
  354.                         die Werte wie nach dem erstmaligen Aufruf einer
  355.                         Routine aus dieser Bibliothek zurückgesetzt!
  356.    
  357.