.TH LIB 1 "07 August 1995"
..
..    This is the documentation for the LIB package, a compatible librarian
..    Copyright (C) 1995,1996,1999  Steffen Kaiser
..
..    This program is free software; you can redistribute it and/or modify
..    it under the terms of the GNU General Public License as published by
..    the Free Software Foundation; either version 2 of the License, or
..    (at your option) any later version.
..
..    This program is distributed in the hope that it will be useful,
..    but WITHOUT ANY WARRANTY; without even the implied warranty of
..    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
..    GNU General Public License for more details.
..
..    You should have received a copy of the GNU General Public License
..    along with this program; if not, write to the Free Software
..    Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
..
..  $Id: DEUTSCH.NRO 3.2 1999/02/03 06:42:46 ska Stab ska $
.de IP

.cu
$0
.en
.SH NAME
lib - Bibliothekar fr OBJ und LIB Dateien
.SH SYNOPSIS
.ul
lib
.bo
[{option}]
libfile
.bo
[{option}] [{command}] [ , listfile ]

.SH DESCRIPTION
.ul
lib
erzeugt eine Bibliothek (LIB Datei), welche Objektmodule (OBJ Dateien)
enthlt. Diese Bibliotheken werden von Linkern weiterverwendet.

.SH OPTIONS

.IP "/?"
Anzeige des Hilfebildschirms.
.IP /A
Intern expandierte Dateinamen werden auch fr "+" Kommandos erlaubt.
Dies ermglicht das Aufrischen von bereits in der Bibliothek enthaltenen
Modulen, anstatt die komplette Bibliothek zu aktualisieren.
Die Option wird ignoriert, falls die
.cu
/G
Option nicht aktiviert wurde. (Siehe dort fr weitere Informationen.)

Alle Module, denen das Kommando "+-" (Ersetzen) zugewiesen wurde, werden
aufgefrischt. Falls keine zum Modul passende OBJ Datei gefunden wird,
verbleibt das Modul in der Bibliothek unverndert und es wird eine Warnung
ausgegeben.
.IP /C
Diese Option bestimmt, da die Gro- und Kleinschreibung der Symbole der
Bibliothek nicht ignoriert werden darf. Dies beeinflut nur die Erzeugung
des Bibliotheksindex', die Symboldefinitionen innerhalb der Module
bleiben unverndert. Sobald die Bibliothek neu erzeugt wird, wird auch
der Index neu erstellt.
.IP /D
Module mit demselben Namen werden innerhalb der Bibliothek akzeptiert.
Das erlaubt sowohl dieselbe Datei mehrfach aufzunehmen, als auch
Dateien unterschiedlichen Inhalts.
.IP /G
Jokerzeichen (Wildcards: * und ?) werden mit den Modulnamen aus der
Bibliothek erweitert. Normalerweise werden Jokerzeichen anhand von
Dateien im Verzeichnissystem expandiert. So entfernt der Aufruf:
.br
.in +5
LIB libfile - m*
.br
.in -5
alle Module, welche auch eine Datei "M*.OBJ" im aktuellen Verzeichnis
besitzten; whrend:
.br
.in +5
LIB libfile /g - m*
.br
.in -5
alle Module aus der Bibliothek entfernt, deren Name mit dem Buchstaben
"M" beginnt.

Diese Option wird ignoriert fr alle Module mit dem Kommando "+", auer
die Option
.cu
/A
ist aktiviert.
.IP /H
Zeigt die Liste der verfgbaren Optionen an.
.IP /I[=[#]]
Erstellt Bibliotheksinformationen in Abhngigkeit von der Seitengre.
Pro Zeile wird die Information ber eine der folgenden Seitengren
dargestellt: die aktuelle, die minimale, die maximale, die optimale
und, falls die Seitengre sich gendert hat, die originale.

Siehe auch das Kapitel: "PAGE SIZE"

Unter der Tabelle wird die Anzahl verwendeter Indexseiten angezeigt.

Die
.bo
aktuelle
Seitengre ist die aktuell in der Bibliothek verwendete Seitengre.

Die
.bo
orignale
Seitengre ist die von der originalen Bibliothek (BAK Datei).

Die
.bo
minimale
Seitengre gibt die kleinste Seitengre an, mit welcher die
Bibliothek erzeugbar ist. Meistens ist sie mit der optimalen identisch.

Die
.bo
maximale
Seitengre ist die Gre des grten OBJ Moduls der Bibliothek. Jede
weitere Erhhung der Seitengre erhht automatisch die Pad Bytes
.bo
aller
Module der Bibliothek.

Die
.bo
optimale
Seitengre wird so kalkuliert, da der Datenbereich der Bibliothek
minimiert wird. Um die Suchzeit nicht unntig zu verlngern, wird eine
Heuristik verwendet, die die Suche auf bestimmte Seitengren einschrnkt.
Das hat zur Folge, da eventuell die optimale verpat wird. Um zu erzwingen,
da alle Seitengren getestet werden, mu die
.cu
/I=0
Option verwendet werden.
.bo
Merke:
Die optimale Seitengre ist die Bibliotheksgre einschlielich der
Pad Bytes, aber nicht einschlielich des Bibliotheksindex' und des
Slack Areas.

Jede Zeile enthlt die folgenden Werte:
.br
.in +3
1) die Seitengre selbst,
.br
2) die Gre des Datenbereichs der Bibliothek mit dieser Seitengre.
.br
3) die Anzahl unbenutzter Pad Bytes der letzten Seite (Slack Area) und
.br
4) die Summe aller sonstigen unbenutzten Pad Bytes des Datenbereichs.
.br
.in -3
Ist das Ausrichten des Bibliotheksindex' nicht abgeschalten (siehe die
.cu
/X
Option), werden die Gren des Slack Areas und des Datenbereiches
aufsummiert und als Datenbereichsgre an Position 2) angezeigt.
Im anderen Fall wird lediglich ein '+' Zeichen zwischen beiden
Positionen angezeigt.

Die Gesamtgre der Bibliothek ergibt sich aus:
.br
.in +3
Der Gre des Datenbereichs
.br
plus der Anzahl Indexseiten * 512.
.br
.in -3

Das optionale Argument dieser Option spezifiziert den Suchbereich genauer.
Je hher die Zahl ist, desto mehr Zeit wird fr die Suche aufgewendet.
Bei Null (0) oder 65535 werden definitiv alle Seiten getestet.

Scheint der Suchbereich recht gro zu werden und ist keine der
Optionen "/S" oder "/Q" aktiv und ist die Standardausgabe nicht
umgeleitet, wird ein Zhler angezeigt.

Der Standardwert von
.cu
/I=
kann mit der
.cu
/V
Option in Kenntnis gebracht werden.

Ohne das Gleichheitszeichen wird der Wert
.bo
1
angenommen, wodurch lediglich die aktuelle, die minimale und die
maximale Seitengren dargestellt werden.
.IP /M
Der Name von neu hinzugefgten Modulen bleibt unverndert.

OBJ Dateien enthalten ein Feld, welches den Modulnamen aufnimmt. Da der
Inhalt dieses Feldes jedoch nicht standardisiert ist, wird normalerweise
der Dateiname in Grobuchstaben verwendet, damit das Modul wieder denselben
Namen erhlt, wird aus der Bibliothek extrahiert.

.ul
Merke:
Ist der Inhalt dieses Feldes nicht als Dateiname verwendbar, kann
das Modul mglicherweise nicht mehr ber die Kommandozeile angesprochen
oder extrahiert werden. Die im Modul gespeicherte Information bleibt
weiterhin nutzbar. (Siehe auch die
.cu
/@=
Option).
.IP /P=#
Setzt die aktuelle Seitengre auf # Byte. Siehe hierzu das Kapitel
"PAGE SIZE".
.IP /Q
Verhindert alle Meldungen auer Warnungen und Fehler.
.IP /S
Verhindert, da ausgegeben wird, welches Modul gerade hinzugefgt,
extrahiert oder entfernt wird.
.IP /V
Zeigt die Versionskontrollinformation, einige Standardwerte und
Grenzen und die Gre des freien DOS Speichers an.
.IP /W
Unterdrckt die Warnung, da ein Modul, welches ber das "-+" Kommando
aufgefrischt werden sollte, sich nicht bereits in der Bibliothek
befindet.
.IP /X
Der Bibliothekindex wird nicht an einer 512 Byte Grenze innerhalb der
Datei ausgerichtet.
Der Index besteht aus Seiten mit einer festen Lnge zu 512 Byte.
Auerdem kann der Index einer der am hufigsten frequentierten
Bereiche der Bibliothek sein. Die Ausrichtung kann deshalb die
Zugriffsgeschwindigkeit verringern.

Im schlechtesten Fall werden durch die Ausrichtung 509 Byte verschwendet.

Ist diese Option aktiviert, bentigt eine leere Bibliothek, welche
kein Modul enthlt, (512 + 2 * Seitengre) Byte, also 544 Byte mit
einer Seitengre von 16 Byte.

Ohne Ausrichtung des Index' reduziert sich die Gre der resultierenden
Bibliothek um das Slack Area, welches mit der
.cu
/I
Option zur Kenntnis genommen werden kann.
.IP /@:file
Aktiviert den speziellen Extrahierungsmodus, wobei der Report in der
Datei "file" abgelegt wird.

Falls die Bibliothek Module enthlt, welche einen unzugnglichen Namen
haben (vgl. di
.cu
/M
Option), ist es mglich, da
.bo
LIB
dieses Modul nicht extrahieren kann. Im speziellen Extrahierungsmodus
ist nur das "*" Kommando erlaubt, auerdem werden Jokerzeichen stets
intern expandiert (vgl. die
.cu
/G
Option). Im Unterschied zum "normalen" Extrahieren von Modulen wird
die OBJ Datei jedoch nicht nach dem Namensfeld des Moduls benannt,
sondern fortlaufend nummeriert. Dieser Proze wird als Report in der
Datei festgehalten und enthlt pro extrahiertem Modul zwei Zeilen:
.br
.in +5
Originalname: "~~~~~~~~~~~"
.br
Neuer Name: "###.OBJ"
.br
.in -5
Wobei ~~~ fr den Inhalt des Namensfelds des Moduls und ### fr die
laufende Nummer steht. Die doppelten Anfhrungszeichen sollen lediglich
die Namen begrenzen.
.bo
Achtung:
Die extrahierten Dateien berschreiben warnunglos existierende Dateien!

.SH COMMANDS

Die Kommandos beschreiben, wie die Bibliothek zu modifizieren ist.
Jedes Kommando hat die Form:
.br
.bo
[{ symbol }] { modulename }
.br

.IP modulename
Diese Liste spezifiziert die betroffenen Module. Whrend des
Entfernens und Extrahierens wird das Namensfeld der Module in der
Bibliothek und whrend des Hinzufgens wird der Dateiname des OBJ
Moduls verglichen.
.bo
modulename
darf Jokerzeichen, einen Pfad und/oder eine Extension enthalten.
Zum Vergleich mit dem Namensfeld wird nur der Namensanteil, d.h. ohne
Laufwerk, Pfad und Extension, verwendet.

.IP "Symbol -"
Bestimmt, da die Module zu entfernen sind.
.IP "Symbol +"
Bestimmt, da die neue OBJ Module oder eine bereits bestehende Bibliothek
hinzuzufgen ist.
.bo
LIB
erkennt whrend des Hinzufgens (und nur hierbei!) automatisch, ob es
sich um ein OBJ Modul oder eine Bibliothek handelt. Die Extension
spielt hierbei keine Rolle.
.IP "Symbol *"
Bestimmt, da die Module aus der Bibliothek extrahiert werden.
Bestehen die Dateien bereits, werden sie ohne Warnung berschrieben.
.IP "Symbol &"
Es wird vollstndig ignoriert. Siehe das Kapitel DIFFERENCES.
.br

Die Symbole
.cu
+
und
.cu
*
drfen nicht kombiniert werden, da es nicht sinnfllig ist, dasselbe
Modul erst zu extrahiern und dann wieder hinzuzufgen. Auch wrde
das alte Modul ein bereits bestehendes vor dessen Hinzufgen berschreiben.

Symbole drfen in einer beliebigen Reihenfolge kombiniert werden und
drfen von Leerzeichen getrennt werden. Ist dasselbe Module mehrfach
in der Liste enthalten, was recht schnell mit Jokerzeichen
passieren kann, behalten alle Symbole ihre Gltigkeit, z.B.:
.br
.in +5
+ module1 * mod*
.br
.in -5
kombinert die Symbole "+" und "*" fr das Module "module1". Das
verursacht einen Fehler, da beide Symbole nicht kombinierbar sind.
.ul
Merke:
Da das Jokerzeichen
.cu
*
ebenso ein gltiges Symbol ist, kann es keinen Modulnamen anfhren. In
diesem Fall mu der Pfad vorangestellt werden, z.B.:
.br
.in +3
.\*.obj
.br
.in -3

.bo
LIB
erlaubt es, Bibliotheken miteinander zu verschmelzen. Ob es sich um eine
Bibliothek handelt, wird erst whrend des Hinzufgens deutlich.
.ul
Merke:
Sind die Symbole "-" oder "*" einer Bibliothek zugeordnet, wird die
Bibliothek solange wie ein OBJ Modul behandelt bis sie tatschlich
hinzugefgt wird, was jedoch erst nach dem Extrahieren und Entfernen
gemacht wird. Die Angabe:
.br
.in +5
lib lib -+ library.LIB
.br
.in -5
meint
.bo
nicht,
da alle Module, die in "library.lib" gespeichert sind, aus "lib.lib"
entfernt werden, bevor sie aus "library.lib" hinzugefgt werden.
Stattdessen wird die Zeile wie folgt interpretiert:
.br
.in +5
lib lib - library.obj + library.lib
.br
.in -5

Wenn die
.cu
/A
Option nicht aktiv ist, werden
.bo
modulenames
mit dem Symbol '+' stets in Abhngigkeit von Dateien expandiert.

.SH "PAGE SIZE"

Eine Seite ist die kleinste adressierbare Einheit einer Bibliothek.
The Spezifikation erlaubt maximal 65.535 Seiten, wobei jedoch bereits
zwei fr interne Zwecke reserviert sind. Jedes Modul beginnt auf einer
neuer Seiten. Das bedeutet auch, da maximal 65.533 Module in einer
Bibliothek gespeichert werden knnen. Sollte eine entsprechende
Fehlermeldung erscheinen, mu eine groe Bibliothek in kleine
aufgeteilt werden.

Die kleinste Seitengre mag variieren, whrend der Manuallegung sind
es 16 Byte, der tatschliche Wert kann jedoch mit der
.cu
/V
Option zur Kenntnis gebracht werden.

Wchst die Zahl der Module an, kann es passieren, da die Standardseitengre
zu klein wird. In diesem Fall erhht
.bo
LIB
automatisch die Seitengre und erzeugt die Bibliothek erneut. Es ist mglich,
da die Seitengre mehrfach angepat werden mu, auch wenn es nicht sehr
wahrscheinlich ist.

Der umgekehrte Fall wird leider nicht untersttzt, d.h.
.bo
LIB
verringert die Seitengre nicht automatisch, z.B. nach dem Entfernen
vieler Module. Die
.cu
/I=
Option schafft hier Abhilfe.

Theoretisch gibt es keinen Grund, bestimmte Seitengren zu meiden,
so ist 61 ebenso gut wie 64.
.bo
LIB
luft weder bei einer sprbar schneller noch langsamer. Es sollte deshalb
diejenige gewhlt werden, die die Bibliotheksgre minimiert. Eine solche
can z.B. so in Erfahrung gebracht werden:
.br
.in +3
LIB /i=0 library.LIB
.br
.in -3

Da der Bibliotheksindex standardmig ausgerichtet wird, mu die optimale
Seitengre nicht unbedingt auch die Dateigre der Bibliothek verringern.
Hierfr mu noch das Ausrichten mittels der
.cu
/X
Option abgeschalten werden.

Einge Bibliothekare scheinen nicht alle Seitengren zu untersttzen,
in diesem Fall sollte eine Seitengre von 16 Byte gewhlt werden.
Linker zeigten dieses Problem bisher nicht.
.SH LISTFILE

Die Listdatei kann optional an die Kommandozeile angehangen
und mu durch ein Komma von den vorherigen Argumenten getrennt werden.
Das Komma darf nicht Teil einer Optionszeichenkette sein!
Ist die Extension nicht angegeben, wird ".LST" verwendet.
Die Listdatei wird ohne Warnung berschrieben, falls sie bereits
existiert.

In die Listdatei werden alle globale Symbole geschrieben, in der
Reihenfolge, wie sie in der Bibliothek auftreten, z.B.:
.br
MSG_0000		size = 513
.br
.ti +4
_E_hlpScreen
.br
MSG_0001		size = 20
.br
.ti +4
_E_rmHlpScreen
.br

Das bedeutet, da die Bibliothek zwei Module enthlt "MSG_0000" und
"MSG_0001".  Das erstere definiert das Symbol "_E_hlpScreen" und das
zweite "_E_rmHlpScreen".

Die Angabe
.bo
"OBJ size = #"
zeigt die Gre der OBJ Datei an, die dieses Modul annehmen wrde.
.SH DIFFERENCES

Es gibt die folgenden dokumentierten Unterschiede zu anderen Bibliothekaren:
.sp
.IP o
Pro Symbol knnen mehrere Module angegeben werden.
.IP o
Die Modulespezifikation kann Jokerzeichen (* und ?) enthalten.
.IP o
Symbole werden nur dann erkannt, wenn sie ein Argument anfhren, z.B.:
"m1+m2" ist nicht identisch zu "m1" "+" "m2".
.IP o
Eine Kommandodatei kann nur Kommandos enthalten, darin sind weder Option
noch der Bibliotheksname noch die Listdatei erlaubt!
.IP o
Die Zeilen in einer Kommandodatei mssen nicht mit dem '&' Zeichen
verbunden werden, z.B. die Sequenz:
.in +4
.br
"+ m1 &
.br
.in +1
+ m2
.br
.in -5
.ti +5
+ m3" wird als "+ m1 + m2 + m3" interpretiert und nicht als "+ m1 + m2".
.IP o
Das Zeichen '&' wird als Symbol ohne jede Bedeutung akzepiert, d.h.
"-+& m1" ist legal und identisch zu "-+ m1".
.IP o
Whrend des Hinzufgens einer Datei entscheidet
.bo
LIB
automatisch, ob es sich um eine Bibliothek oder um ein OBJ Modul handelt.
Ist es eine Bibliothek, werden alle darin enthaltenen Module hinzugefgt.
Ist es ein OBJ Modul, wird nur dieses Modul hinzugefgt.
.IP o
Das Komma, welches die Listdatei von den vorherigen Teilen der Kommandozeile
trennt, mu von den Optionen durch ein Leerzeichen getrennt sein, ansonsten
wird das Komma als Option interpretiert und erzeugt einen Fehler.
.IP o
Einige Bibliothekare knnen nur Bibliotheken mit bestimmten Seitengren
verarbeiten.
.SH ERRORLEVELS
.IP 0
Kein Fehler oder nur niedere Warnungen sind aufgetreten.
.IP 3
^Break oder ^C gedrckt.
.IP 100
Eine Datei konnte nicht gefunden werden, die hinzugefgt werden soll.
.IP 101
Ein zu lschendes oder zu extrahierendes Modul ist nicht in der Bibliothek.
.IP 102
Die Bibliothek enthlt dasselbe Symbol mehrfach.
.IP 103
Ein Model, welches hinzugefgt werden soll, ist bereits enthalten.
.IP 125
Versionsinformation ausgegeben.
.IP 127
Hilfebildschirm ausgegeben.
.IP "alle anderen"
Ein (schwerwiegender) Fehler.
.br
Falls mehr als eine Warnung mit einem Errorlevel von 100 bis 103 auftritt,
wird nur der Errorlevel der letzten zurckgegeben.
.SH "SEE ALSO"
Compiler, Assembler, Linker.
.SH "KNOWN BUGS"
.IP o
Da die Zeichen '*' und '-' sowohl gltige Symbole als auch gltig im
Modulname sind, drfen Modulnamen nicht damit beginnen; es kann
einfach der Pfad vorangesetzt werden, z.B.:
.br
"+ *.obj" ==> "+ .\\*.obj"
.IP o
Die kleinste erstellbare Bibliothek hat eine Gre von 1024 Byte;
512 Byte fr eine Bibliotheksindexseite und 32 Byte fr zwei
Bibliotheksseiten. Da jedoch der Index auf eine durch 512 teilbare
Adresse ausgerichtet wird, werden noch 480 Pad Bytes eingefgt.
Siehe auch die
.cu
/X
Option.
.IP o
berlappen sich mehrere Modulspezifikationen ist undefiniert, welches
Symbol mit welchem Modul gekoppelt wird, auch ist mglich, da einige
Modulangaben miteinander verschmelzen.
Die meisten solcher berlappungen werden jedoch entsprechend gewarnt.
.IP o
Kann ein Modul, welches mittels der Symbole "-+" ersetzt werden soll,
nicht zum Lesen geffnet werden (die Existenz wurde bereits geprft),
ist das Modul aus der Bibliothek entfernt und kann nicht hinzugefgt
werden. In diesem Falle sollte die BAK Datei der Bibliothek helfen.
.IP o
Solange eine Datei nicht zur Bibliothek hinzugefgt wird, wird sie als
OBJ Modul interpretiert. Deshalb sollte beim Hinzufgen von Bibliotheken
nur das Symbol "+" Verwendung finden.
.SH EXAMPLES

.IP "lib /c msg + ./* , msg.lst"
.br
Fgt der Bibliothek MSG.LIB alle *.OBJ Dateien im aktuellen
Verzeichnis hinzu und erstellt die Listdatei MSG.LST. Sollte MSG.LIB
noch nicht existieren, wird sie erzeugt.

.IP "lib /c msg /g - ./*"
.br
Lscht alle Module in der Bibliothek.

.IP "lib msg /cg -+ ./*"
.br
Entfernt alle Module aus der Bibliothek, welche auch eine korrespondierene
OBJ Datei im aktuellen Verzeichnis besitzen. Anschlieend werden alle
OBJ Dateien aus dem aktuellen Verzeichnis hinzugefgt. Das bedeutet,
da die Bibliothek aktualisiert wird.

.IP "lib msg /cga -+ ./*"
.br
Entfernt alle Module aus der Bibliothek, welche auch eine korrespondierene
OBJ Datei im aktuellen Verzeichnis besitzen. Anschlieend werden die 
OBJ Dateien hinzugefgt. Das bedeutet, da die Bibliothek aufgefrischt
wird. Es werden keine Module hinzugefgt, die nicht bereits enthalten sind.

.SH DISCLAIMER

Diese Software untersteht der GNU GPL Version 2 oder hher.
Sie besagt unter anderem, da die Autoren fr nichts haftbar gemacht
werden knnen. Sind Sie mit der GNU GPL nicht einverstanden,
drfen Sie weder die Quelltexte noch die ausfhrbaren Dateien
weiterverwenden!

Librarian for LIB/OBJ compatible libraries and modules
.br
Copyright (C) 1995,1996  Steffen Kaiser
.sp
This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.
.sp
This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.
.sp
You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.

.SH CONTRIBUTERS
.rm -10
.ce 4
Steffen Kaiser
.br
Ernst-Thlmann-Strae 2
.br
D-39606 Iden
.br
Deutschland - Germany
.br
.rm +10

e-mail: Steffen.Kaiser@T-Online.DE


.br
James W. Lynch
.br
e-mail: jwl@atlanta.cray.com


.br
Vielen Dank an den anonymen Zusammensteller der OBJLIB.ZIP Datei,
welcher von sich selbst nur als "mir" spricht.