P8000/WEGA/contrib/ingres/dbs/ing_src/teil2/lib

.ds RF \f3LIBRARY       \f1
.ds RH \f3GUTIL       \f1
.ds CH - % -
.ds LH Anwendung
.ds LF ING_DB 6.3/0
.bp
.NH 2
.ft B
Bibliotheksfunktionen **
.ft R
.LP
.sp 10
.NH 3
.ft B
Vorbemerkung **
.ft R
.LP
Zwangsl\o'a"'ufig werden bei einem so umfangreichen
Programmkomplex wie ING_DB eine Reihe von Bibliotheken
verwendet. Dieser Abschnitt soll keine Erl\o'a"'uterungen
zum Inhalt und zur Leistung der einzelnen Prozeduren
und Funktionen
bringen, es soll nur auf einige Besonderheiten
hingewiesen werden. Mit dem \o'U"'bergang von UNIX Version 6
zu Version 7 wurden die Konvertierungsfunktionen
.ft B
atoX
.ft R
in ihrer Parameter\o'u"'bergabe bzw. -\o'u"'bernahme nicht
den Bedingungen der V7-Bibliothek 
.ft B
libc.a
.ft R
angepasst. Es ist deshalb sinnvoll in AMX-Programmen
grunds\o'a"'tzlich die V6-Variante zu verwenden, um die
Namensgleichheit zu \o'u"'berbr\o'u"'cken.
.LP
Dar\o'u"'berhinaus kennt die Bibliothek 
.ft B
gutil
.ft R
eine Reihe von Funktionen, deren Anwendung durchaus
Erleichterungen bei der Programmierung in C bringen kann,
ohne das Gesamtkonzept zu st\o'o"'ren. Allerdings wird
nachfolgend nur ein sehr bescheidener Teil der Prozeduren
beschrieben.
.NH 3
.ft B
Funktionen **
.ft R
.LP
------------------------------------------------------------
.sp 2
.DS C
 \f3APPEND      \f1
.DE
.ft B NAME
.IP
append - Block-Verkettung
.RE
.sp 1
.ft B
SYNOPSIS
.ft R
.IP
.DS L
append (b1, l1, b2, l2, b3)
int     l1, l2;
char    *b1, *b2, *b3;
.DE
.RE
.sp 1
.ft B
BESCHREIBUNG
.ft R
.IP
Die Bl\o'o"'cke b1 und b2,  jeweils mit der L\o'a"'nge l1 und l2, werden
zum Block b3 verkettet. "return" erfolgt mit der Adresse des
ersten Bytes nach b3.
.RE
.sp 1
.ft B
FEHLER
.ft R
.IP
Es wird nicht gepr\o'u"'ft,  ob die Bl\o'o"'cke in unzul\o'a"'ssiger Weise
\o'u"'berlappen.
.RE
.LP
------------------------------------------------------------
.sp 2
.DS C
 \f3ATOF      \f1
.DE
.ft B
NAME
.ft R
.IP
atof - konvertiert eine Zeichenkette in eine Float-Zahl
.RE
.sp 1
.ft B
SYNOPSIS
.ft R
.IP
.DS L
atof (str, val)
char    *str;
double  *val;
.DE
.RE
.sp 1
.ft B
BESCHREIBUNG
.ft R
.IP
atof konvertiert eine durch str adressierte Zeichenkette in eine
float-Zahl. Das Ergebnis steht auf der durch val adressierten
Variablen.
.br
.RS
.IP return: 8
-1  Syntaxfehler
.br
0  keine Fehler
.br
1  \o'U"'berlauf
.RE
.sp 1
Syntax:
.IP
{<sp>}[+|-]{<sp>}{<Ziffer>}[. <Ziffer>]{<sp>}[<exp>]
.sp
wobei "sp" ein Leerzeichen, exp=[e|E]<int> der Exponent und int
eine Integer Zahl im Sinne der Konvertierungsfunktion atoi ist.
.RE
.sp 1
.ft B
SIEHE-AUCH
.ft R
.IP
atoi()
.RE
.LP
------------------------------------------------------------
.sp 2
.DS C
 \f3ATOI      \f1
.DE
.ft B
NAME
.ft R
.IP
atoi - konvertiert eine Zeichenkette in eine Integerzahl
.RE
.sp 1
.ft B
SYNOPSIS
.ft R
.IP
.DS L
atoi (str, val)
char    *str;
int     *val;
.DE
.RE
.sp 1
.ft B
BESCHREIBUNG
.ft R
.IP
atoi konvertiert eine durch str adressierte Zeichenkette
in eine 16-Bit Integer-Zahl.
Das Ergebnis steht auf der durch val adressierten Variablen.
.br
.RS
.IP return: 8
-1  Syntaxfehler
.br
0  keine Fehler
.br
1  \o'U"'berlauf
.RE
.sp 1
Syntax:
.IP
{<sp>}[+|-]{<sp>}{Ziffer}{<sp>}
.RE
.LP
------------------------------------------------------------
.sp 2
.DS C
 \f3ATOL      \f1
.DE
.ft B
NAME
.ft R
.IP
atol - konvertiert eine Zeichenkette in eine Long-Zahl
.RE
.sp 1
.ft B
SYNOPSIS
.ft R
.IP
.DS L
atol (str, val)
char    *str;
int     *val;
.DE
.RE
.sp 1
.ft B
BESCHREIBUNG
.ft R
.IP
atol konvertiert eine durch str adressierte Zeichenkette
in eine 32-Bit Integer-Zahl.
Das Ergebnis steht auf der durch val adressierten Variablen.
.RS
.IP return: 8
-1  Syntaxfehler
.br
0  keine Fehler
.br
1  \o'U"'berlauf
.RE
.sp 1
Syntax:
.IP
{<sp>}[+|-]{<sp>}{Ziffer}{<sp>}
.RE
.LP
------------------------------------------------------------
.sp 2
.DS C
 \f3BEQUAL        \f1
.DE
.ft B
NAME
.ft R
.IP
bequal - Test auf Blockgleichheit
.RE
.sp 1
.ft B
SYNOPSIS
.ft R
.IP
.DS L
bequal (a, b, l)
char    *a, *b;
int     l;
.DE
.RE
.sp 1
.ft B
BESCHREIBUNG
.ft R
.IP
.ft B
bequal 
.ft R
testet zwei Bl\o'o"'cke a und b, beide in der L\o'a"'nge l,
auf Gleichheit.
.RS
.IP return: 8
1  bei Gleichheit
.br
0  bei Ungleichheit
.RE
.RE
.LP
------------------------------------------------------------
.sp 2
.DS C
 \f3BITPOS        \f1
.DE
.ft B
NAME
.ft R
.IP
bitpos - h\o'o"'chstwertige Bitposition ermitteln
.RE
.sp 1
.ft B
SYNOPSIS
.ft R
.IP
bitpos (w)
.br
int	w;
.RE
.sp 1
.ft B
BESCHREIBUNG
.ft R
.IP
bitpos ermittelt die Stellung des h\o'o"'chstwertigen Bits
der 16-Bit Integer-Zahl w.
Die Bits werden von rechts nach links, beginnend mit Null,
aufsteigend numeriert.
.RS
.IP return: 8
0, . . . , 15 entsprechend der Bitposition,
.br
-1       wenn kein Bit gesetzt ist.
.RE
.RE
.LP
------------------------------------------------------------
.sp 2
.DS C
 \f3BMOVE       \f1
.DE
.ft B
NAME
.ft R
.IP
bmove - Block Transport
.RE
.sp 1
.ft B
SYNOPSIS
.ft R
.IP
.DS L
char *bmove (a, b, l)
char    *a, *b;
int     l;
.DE
.RE
.sp 1
.ft B
BESCHREIBUNG
.ft R
.IP
bmove transportiert l Bytes von a nach b.
Die Sinnf\o'a"'lligkeit von l und ein "\o'U"'berlauf" von b
werden nicht gepr\o'u"'ft.
.IP
"return" erfolgt mit der Adresse des l+1. Elementes von b.
.RE
.LP
------------------------------------------------------------
.sp 2
.DS C
 \f3CONCAT        \f1
.DE
.ft B
NAME
.ft R
.IP
concat - Zeichenketten Verkettung
.RE
.sp 1
.ft B
SYNOPSIS
.ft R
.IP
.DS L
char *concat (s1, s2, s3)
char    *s1, *s2, *s3;
.DE
.RE
.sp 1
.ft B
BESCHREIBUNG
.ft R
.IP
Die Zeichenketten s1 und s2 werden zur Zeichenkette s3 verkettet.
Dabei d\o'u"'rfen s1 und s3 \o'u"'berlappen.
"return" erfolgt mit der Adresse des letzten Bytes  (Null-Byte)
von s3.
.RE
.LP
------------------------------------------------------------
.sp 2
.DS C
 \f3FTOA      \f1
.DE
.ft B
NAME
.ft R
.IP
ftoa - konvertiert eine Gleitkommazahl in eine Zeichenkette
.RE
.sp 1
.ft B
SYNOPSIS
.ft R
.IP
.DS L
ftoa (val, str, l, prec, form)
.br
double  val;
.br
char    *str, form;
.br
int     l, prec;
.DE
.RE
.sp 1
.ft B
BESCHREIBUNG
.ft R
.IP
ftoa konvertiert eine doppeltgenaue Gleitkommazahl val in eine
entsprechende Zeichenkette str. Die Zeichenkette str muss
mindestens in der L\o'a"'nge l+1 vereinbart sein.
Die Genauigkeit prec gibt die Anzahl der Stellen nach dem
Dezimalpunkt an. Mit "form" wird das
Ausgabeformat festgelegt.
Es kann die Werte e, E, f, F, g, G, n<, N annehmen. E steht f\o'u"'r die
exponentielle- und F f\o'u"'r die Gleitkommadarstellung. G und N sind
analog zu F; passt die konvertierte Zahl aber nicht in die
Ausgabebreite, wird auf die exponentielle Form umgeschaltet.
G garantiert die Ausrichtung des Dezimalpunktes, N nicht.
.RE
.LP
------------------------------------------------------------
.sp 2
.DS C
 \f3GETSTR        \f1
.DE
.ft B
NAME
.ft R
.IP
getstr - liesst eine Zeichenkette von der Standard-Eingabe
.RE
.sp 1
.ft B
SYNOPSIS
.ft R
.IP
.DS L
getstr (str, d, n)
char    *str, d;
int     n;
.DE
.RE
.sp 1
.ft B
BESCHREIBUNG
.ft R
.IP
Es werden Zeichen von der Standard-Eingabe nach str \o'u"'bertragen
und zwar solange, bis der Begrenzer
.ft B
d
.ft R
erkannt wird.
Dabei werden h\o'o"'chstens n Zeichen \o'u"'bertragen. Wenn der
Begrenzer nach n Zeichen noch nicht erkannt wurde,
werden alle weiteren Zeichen bis zur Erkennung des Begrenzers
\o'u"'bergangen. An Stelle des Begrenzers wird in jedem Falle
das Null-Byte \o'u"'betragen, sodass das Feld str mindestens von
der L\o'a"'nge n+1 sein muss.
"return" erfolgt mit dem Wert 1. Sollte vor der Erkennung des
Begrenzers das file-Ende erkannt werden, wird die Zeichenkette
ebenfalls mit dem Null-Byte abgeschlossen. "return" erfolgt dann
mit dem Wert 0.
.RE
.LP
------------------------------------------------------------
.sp 2
.DS C
 \f3IOCV      \f1
.DE
.ft B
NAME
.ft R
.IP
iocv - konvertiert eine Integer-Zahl in eine Zeichenkette
.RE
.sp 1
.ft B
SYNOPSIS
.ft R
.IP
.DS L
iocv (i)
int   i;
.DE
.RE
.sp 1
.ft B
BESCHREIBUNG
.ft R
.IP
Die Integer-Zahl i wird mittels der Funktion itoa in eine
Zeichenkette konvertiert. Das Ergebniss wird in einem internen
statischen Bereich gespeichert, dessen Adresse durch
"return" zur\o'u"'ckgegeben wird.
.RE
.sp 1
.ft B
SIEHE AUCH
.ft R
.IP
itoa ()
.RE
.LP
------------------------------------------------------------
.sp 2
.DS C
 \f3ITOA      \f1
.DE
.ft B
NAME
.ft R
.IP
itoa - konvertiert 16-Bit Integerzahl in Zeichenkette
.RE
.sp 1
.ft B
SYNOPSIS
.ft R
.IP
.DS L
itoa (i, str)
int     i;
char    *str;
.DE
.RE
.sp 1
.ft B
BESCHREIBUNG
.ft R
.IP
Die Integer-Zahl i wird in eine 7 Byte lange Zeichenkette konvertiert
und in dem durch str adressierten Feld gespeichert.
.RE
.LP
------------------------------------------------------------
.sp 2
.DS C
 \f3LENGTH        \f1
.DE
.LP
.ft B
NAME
.ft R
.IP
length - ermittelt die L\o'a"'nge einer Zeichenkette
.RE
.sp 1
.ft B
SYNOPSIS
.ft R
.IP
.DS L
length (str)
char    *str;
.DE
.RE
.sp 1
.ft B
BESCHREIBUNG
.ft R
.IP
Es wird die Anzahl der Bytes einer Zeichenkette, mit Ausnahme
des die Kette abschliessenden Null-Bytes, ermittelt und
durch "return" zur\o'u"'ckgegeben.
.RE
.LP
------------------------------------------------------------
.sp 2
.DS C
 \f3OATOI        \f1
.DE
.ft B
NAME
.ft R
.IP
oatoi -	konvertiert eine Zeichenkette, die eine Oktalzahl
darstellt, in eine Integer-Zahl
.RE
.sp 1
.ft B
SYNOPSIS
.ft R
.IP
.DS L
oatoi (str)
char   *str;
.DE
.RE
.sp 1
.ft B
BESCHREIBUNG
.ft R
.IP
oatoi konvertiert die Zeichenkette str, die nur oktale Ziffern
und kein Vorzeichen enthalten darf, in eine 16-Bit Integer-Zahl.
Die Konvertierung wird beendet, sobald ein Zeichen ungleich einer
Oktalziffer erkannt wird. Der konvertierte Wert wird durch
"return" zur\o'u"'ckgegeben.
.RE
.LP
------------------------------------------------------------
.sp 2
.DS C
 \f3PAD     \f1
.DE
.ft B
NAME
.ft R
.IP
pad - f\o'u"'llt eine Zeichenkette mit Leerzeichen auf
.RE
.sp 1
.ft B
SYNOPSIS
.ft R
.IP
.DS L
pad (str, l)
char    *str;
int     l;
.DE
.RE
.sp 1
.ft B
BESCHREIBUNG
.ft R
.IP
pad f\o'u"'llt die Zeichenkette str vom Null-Byte an bis zum
Erreichen der l-ten Position mit Leerzeichen, vorausgesetzt,
l ist gr\o'o"'sser als die L\o'a"'nge der Zeichenkette.
Erf\o'u"'llt l diese Bedingung nicht, wird die Kette nicht ver\o'a"'ndert.
pad wird durch den Aufruf von pmove (str, str, l, ' ') realisiert.
.RE
.sp 1
.ft B
SIEHE AUCH
.ft R
.IP
pmove ()
.RE
.LP
------------------------------------------------------------
.sp 2
.DS C
 \f3PMOVE       \f1
.DE
.ft B
NAME
.ft R
.IP
pmove - transportiert eine Zeichenkette und f\o'u"'llt auf
.RE
.sp 1
.ft B
SYNOPSIS
.ft R
.IP
.DS L
char *pmove (str, b, l, c)
char    *str, *b, c;
int     l;
.DE
.RE
.sp 1
.ft B
BESCHREIBUNG
.ft R
.IP
pmove transportiert die Zeichenkette str in den Speicherbereich b.
Dabei werden genau l Bytes \o'u"'bertragen. Ist die Zeichenkette l\o'a"'nger,
wird abgeschnitten, ist sie k\o'u"'rzer, wird ab Nullbyte mit dem Zeichen
c aufgef\o'u"'llt.
.RE
.lP
------------------------------------------------------------
.sp 2
.DS C
 \f3PRARGS        \f1
.DE
.ft B
NAME
.ft R
.IP
prargs - protokolliert die Argumente einer Kommandozeile
.RE
.sp 1
.ft B
SYNOPSIS
.ft R
.IP
.DS L
prargs (pc, pv)
int     pc;
char    **pv;
.DE
.RE
.sp 1
.ft B
BESCHREIBUNG
.ft R
.IP
prargs protokolliert \o'u"'ber Standardausgabe die Argumente einer
Kommandozeile  (main(argc, argv)). Dabei werden Sonderzeichen
(Zeichen, deren oktaler Code zwischen 040 und 0177 liegt)
als Oktalzahl protokolliert.
.RE
.LP
------------------------------------------------------------
.sp 2
.DS C
 \f3SCOMPARE          \f1
.DE
.ft B
NAME
.ft R
.IP
scompare - vergleicht zwei Zeichenketten
.RE
.sp 1
.ft B
SYNOPSIS
.ft R
.IP
.DS L
scompare (stra, la, strb, lb)
char    *stra, *strb;
int     la, lb;
.DE
.RE
.sp 1
.ft B
BESCHREIBUNG
.tf R
.IP
Zwei Zeichenketten stra und strb werden auf der Basis ihres
ascii-Codes verglichen. Die Anzahl der zu vergleichenden Zeichen
wird durch la bzw. lb definiert.
Die Zeichenkettenl\o'a"'ngen sollten mindestens so gross, wie die
angegebenen Vergleichsl\o'a"'ngen la und lb sein, andernfalls wird
als Vergleichswert das Nullbyte benutzt.
Werden die L\o'a"'ngen la und lb mit dem Wert Null angegeben, so
wird daf\o'u"'r automatisch ein Maximalwert  (32767) benutzt.
Ebenso wird, falls la und lb ungleich sind f\o'u"'r die Kette
mit der kleineren Vergleichsl\o'a"'nge das Nullbyte zum Vergleich benutzt.
Leerzeichen werden \o'u"'bergangen.
IP return: 8
-1 stra < strb
.br
 0 stra = strb
.br
 1 stra > strb
.RE
.LP
------------------------------------------------------------
.sp 2
.DS C
 \f3SEQUAL        \f1
.DE
.ft B
NAME
.ft R
.IP
sequal - testet zwei Zeichenketten auf Gleichheit
.RE
.sp 1
.ft B
SYNOPSIS
.ft R
.IP
.DS L
sequal (stra, strb)
.br
char    *stra, *strb;
.DE
.RE
.sp 1
.ft B
BESCHREIBUNG
.ft R
.IP
Zwei Zeichenketten stra und strb werden auf absolute Gleichheit getestet.
"return" erfolgt mit 1 bei Gleichheit, sonst mit 0.
.RE
.LP
------------------------------------------------------------
.sp 2
.DS C
 \f3SMOVE       \f1
.DE
.ft B
NAME
.ft R
.IP
smove - Zeichenkette transportieren
.RE
.sp 1
.ft B
SYNOPSIS
.ft R
.IP
.DS L
smove (str, b)
.br
char   *str, *b;
.DE
.RE
.sp 1
.ft B
BESCHREIBUNG
.ft R
.IP
Die Zeichenkette str wird zum Block b transportiert.
"return" erfolgt mit der L\o'a"'nge der transportierten Zeichenkette.
.RE
.LP
------------------------------------------------------------
.sp 2
.DS C
 \f3SYSERR        \f1
.DE
.ft B
NAME
.ft R
.IP
syserr - Systemfehlermitteilung und Abbruch
.RE
.sp 1
.ft B
SYNOPSIS
.ft R
.IP
.DS L
syserr (ptr)
char    *ptr;
.DE
.RE
.sp 1
.ft B
BESCHREIBUNG
.ft R
.IP
syserr liefert eine Fehlermitteilung \o'u"'ber Standardausgabe
und bricht im Normalfall durch Aufruf der Funktion exit ab.
Argumente f\o'u"'r syserr sind in der gleichen Form
wie bei printf anzugeben. Sie sind allerdings in ihrer
Anzahl auf 5 beschr\o'a"'nkt.
syserr unterscheidet zwei Aufrufarten:
.RS
.IP 1.
der erste Parameter ist Null  (die folgenden Parameter
wie bei printf), dann wird genau die
printf Funktion realisiert.
.IP 2.
Der erste Parameter ist nicht Null  (also alle Parameter
wie bei printf), dann wird mit Hilfe der externen Variablen
char *Proc_name und int erron, Acceerror eine erweiterte
Fehlerprotokollierung realisiert  (UNIX error,
ACCESS METHOD error, mit Angabe einer Fehlernummer
und eventuell vorangestelltem Programmnamen).
.RE
.RE
.LP
------------------------------------------------------------
.sp 2
.DS C
 \f3XPUTCHAR           \f1
.DE
.ft B
NAME
.ft R
.IP
xputchar - Zeichenausgabe \o'u"'ber Standard-output
.RE
.sp 1
.ft B
SYNOPSIS
.ft R
.IP
.DS L
xputchar (c)
.br
char    c;
.DE
.RE
.sp 1
.ft B
BESCHREIBUNG
.ft R
.IP
xputchar \o'u"'bertr\o'a"'gt alle Zeichen mit Ausnahme derer,
deren oktaler Code gr\o'o"'sser als 040
und kleiner als 0200 ist (Sonderzeichen)
mittels der Funktion putchar zur Standardausgabe.
Sonderzeichen werden mittels printf als Oktalzahl
zur Standardausgabe geleitet.
Diesen wird das Zeichen "\\" vorangestellt.
.RE
.sp 1
.ft B
SIEHE AUCH
.ft R
.IP
printf (), putchar()
.RE
.LP
------------------------------------------------------------
.sp 2
.DS C
 \f3ZTACK       \f1
.DE
.ft B
NAME
.ft R
.IP
ztack - Zeichenkettenverkn\o'u"'pfung in einem Puffer
.RE
.sp 1
.ft B
SYNOPSIS
.ft R
.IP
.DS L
char *ztack (stra, strb()
.br
char    *stra;
char    *strb;
.DE
.RE
.sp 1
.ft B
BESCHREIBUNG
.ft R
.IP
Die Zeichenketten stra und strb werden in einem
statischen Pufferbereich zu einer Zeichenkette verbunden.
"return" erfolgt mit der Anfangsadresse
des Puffers. Bei Puffer\o'u"'berlauf wird mittels Funktion syserr
der Fehlersachverhalt "ztack overflow" nebst Pufferinhalt mitgeteilt.
Der Puffer fasst maximal 100 Zeichen, wobei das Programm so angelegt ist,
das erst nach dem Umspeichern der Zeichenkette in den Puffer auf \o'U"'berlauf
getestet wird. Ein rekursiver Aufruf von ztack ist m\o'o"'glich
(ztack(ztack(x, y), z)).
.RE
.sp 1
.ft B
SIEHE AUCH
.ft R
.IP
syserr ()
.RE