avanti-Auftragssprache, Sonderbefehle und Fehlermeldungen
Der avanti-Server kann sog. "Aufträge" abarbeiten. Dies erledigt in Wirklichkeit das Programm acon , das dazu von avanti aufgerufen wird.
Ein Auftrag (engl. job) ist eine Kette von Befehlen, formuliert in der avanti-Sprache. Der Server kann diese Befehle ausführen. Aus der avanti-Sprache ist die FLEX -Sprache des Windows-Programms a99/alcarta ursprünglich hervorgegangen und hat sich dann teilweise verselbständigt, denn a99 ist ein interaktives Programm mit Windows-Oberfläche und stellt viele zusätzliche Anforderungen. Daraus erwuchsen neue Befehle, die acon nicht kennt und nicht ausführen könnte. Leider gibt es bei den gemeinsamen Befehlen auch kleinere Unterschiede, die nicht nötig gewesen wären, auf die bei der Beschreibung der einzelnen Befehle aber hingewiesen wird.
Beispiel für einen Job: (Zeilennummern nur zur Verdeutlichung, sie stehen nicht in der Jobdatei!)
Zeile Anweisungen Bedeutung
1 & c:\allegro // & leitet einen neuen Auftrag ein
2 find YOP>1990 // Restriktion setzen
3 find PER shake? // Trunkierte Suche im Personenregister
4 list // Kurztitel der Ergebnisse
5 @ DB=avdemo ID=admin/MASTER
// Auswahl der Datenbank, ClientID
6 AVANTI:EOJ // Ende-Signal
Das Konsolprogramm acon braucht die Zeilen 1, 5 und 6 nicht unbedingt.
Für das Zusammenspiel zwischen avanti und acon von besonderer Bedeutung sind die Steuerzeilen 1 und 5, und zwar:
Das &-Zeichen muß am Beginn eines Auftrags stehen. Hinter dem & kann ein Pfadname folgen („virtueller Aufrufpfad"). Dort sucht der Server Parameter-Dateien, die im Datenbankverzeichnis nicht gefunden werden. Die Suchreihenfolge ist diese:
1. Datenbankverz.
2. Programmverz. (wo avanti gestartet wurde), denn acon wird gleichfalls dort gestartet
3. virtueller Aufrufpfad (steht in Zeile 1 hinter & )
Als Abschlußzeile muß dem Avanti-Server die gewünschte Datenbank und der Benutzername mitgeteilt werden. Diese Steuerzeile wird durch das Zeichen @ eingeleitet. Aber erst wenn der End-of-Job-Befehl (Zeile 6) angekommen ist, beginnt die Abarbeitung des Auftrags - nicht früher, d.h. der gesamte Job wird zuerst einmal eingelesen.
Wie ein solcher Auftrag an den Server übergeben und wie das Ergebnis angenommen wird, kann man z.B. in der Skriptdatei av_ini.php des Paketes phpac sehen, und zwar in der Funktion sendjob().
Die Zeilen 2 bis 4 sind die eigentlichen Anweisungen, die an der Datenbank ausgeführt werden sollen.
Für avanti (d.h. acon) gelten folgende allgemeine, von a99 abweichende Regeln:
· Das &-Zeichen, am Anfang der ersten Zeile stehend, markiert den Beginn eines neuen Auftrags
· Befehlszeilen dürfen mit einem oder mehreren Leerzeichen beginnen (!!)
· Mehrfach-Leerzeichen sind erlaubt, sie wirken wie nur ein Leerzeichen. (In "write"-Befehlen innerhalb von "..." oder '...' bleiben sie aber erhalten)
· Tabulatorzeichen wirken wie Leerzeichen.
· Kommentare werden mit // (Doppelschrägstrich) eingeleitet und können überall stehen. Der Rest der Zeile wird dann ignoriert. Kommentare sollten aus Zeitgründen evtl. nicht allzu üppig sein.
· In einer Zeile können mehrere Befehle stehen, sie müssen dann mit Semikolon ';' getrennt werden. Kommt in einem Suchbegriff ein Semikolon vor, muß der Text in Anführungszeichen eingeschlossen werden.
· ERROR (in der Befehlsbeschreibung) bedeutet: es wird der Fehlerzustand gesetzt, wenn bei dem Befehl was schiefging.
Mit dem Befehl: if error anweisung oder if ok anweisung in der nachfolgenden Zeile kann man darauf reagieren und woanders hinspringen, wenn ein Fehler aufgetreten ist bzw. wenn alles ok ist. Die anweisung kann aber auch eine Folge mehrerer Befehle sein, mit ; als Trennung.
Es folgen nun die avanti-Sonderbefehle
Auch der Befehl list ist auf avanti beschränkt, wird aber in einem eigenen Text beschrieben.
@ DB=datenbank ID=user/PASSWORD
Zugriffs-Steuerzeile am Ende des Auftrags.
Da der Avanti-W Server mehrere Datenbanken ansprechen kann, muß der Client dem Server die gewünschte und dem Server bekannte Datenbank während der Jobübergabe mitteilen.
Außerdem sollte sich der Anwender durch die Angabe eines eingetragenen Nutzernamens + Password identifizieren, falls er mehr als nur Lesezugriff erwartet.
Dabei steht datenbank für ein dem Avanti-Server bekannten Alias-Namen der gewünschten Datenbank und user/password identifiziert den Benutzer.
Der Server vergleicht diese Angaben mit den Eintragungen in seiner Datei avanti.conf
Beispiel: @ DB=avdemo ID=opac/opac
Die Steuerzeile ist, das sei nochmals betont, die letzte Zeile eines Auftrags. In dieser Zeile keine Leerzeichen weglassen oder hinzufügen.
Das Paßwort hinter dem / muß exakt stimmen, auch hinsichtlich Groß-/Kleinschreibung, die bei den anderen Angaben egal ist.
echo off
unterdrückt sämtliche Meldungen an den Client, die im Verlauf des Auftrags auftreten können, incl. der Fehlermeldungen.
Evt. auftretende Fehler müssen mit Hilfe der Bedingungsprüfung if error aufgefangen werden. Eine Meldung kann dann im Fehlerfall mit dem write-Befehl selbst generiert werden.
Der Befehl echo off wird in komplexen Aufträgen eingesetzt, um bei der Weiterbearbeitung von Teilergebnissen nicht zuvor die Meldungen des avanti- Servers herausfiltern zu müssen.
echo on
hebt ein vorangegangenes echo off auf.
Fehlerbedingungen
avanti liefert genauere Fehlerangaben als a99.
Dazu gibt es eine Erweiterung des Befehls if error :
if error[= qualifier] command
Wenn ein Fehler beim vorangegangenen Befehl auftrat, dann command ausführen. (Das kann eine Folge von Befehlen sein).
Die optionale Ergänzung qualifier differenziert den zu überprüfenden Fehlerstatus. Dafür kann man folgende Zeichenketten einsetzen:
qualifier Bedeutung
locked Datensatz ist gesperrt
noaccess (Schreib-)Zugriff wurde verweigert
writeerror allgemeiner Fehler beim Schreiben in dieDatenbank (put, update).
xporterror allgemeiner Fehler beim export-Befehl (meist Fehler in Param.Datei)
readerror allgemeiner Fehler beim read-Befehl
ordererror allgemeiner Fehler beim order-Befehl
qrixerror allgemeiner Fehler beim qrix-Befehl
norecord kein Datensatz geladen
nofile ein (Parameter)-File konnte nicht geöffnet werden
overflow 1. zuviele Treffer (find-Befehl)
2. die auszugebende Datenmenge konnte vom Ergebnisspeicher nicht aufgenommen werden. Der Auftrag wurde unvollständig ausgeführt.
foundnothing kein Treffer (find-Befehl)
endindex durch einen vorangegangenen qrix-Befehl wurdedas Registerende erreicht oder überschritten.
unknown allgemeiner Fehler (kann immer geprüft werden). Die Angabe unknown entspricht derPrüfung ohne =qualifier.
Nach Auftreten eines Fehlers ist eine interne Fehlernummer gesetzt. Diese kann man sich mit dem Befehl var Err in die iV schreiben lassen.
--------------------------------------------------------------
compress obsolet
avanti verfügt(e) über die Möglichkeit, den Ergebnisspeicher nach dem ZIP-Methode zu komprimieren.
Dazu muß vor dem ersten Ausgabebefehl (list, download, qrix der Befehl compress angegeben werden.
Vorteile der Komprimierung: Die Belastung im Übertragungskanal zwischen Server und Client sinkt. Das übertragene Ergebnis enthält nach der Komprimierung in der ersten Zeile den Eintrag:
ZLIB:START_COMPRESSED.LENGTH=<Zahl>
Die Startsequenz ZLIB:START_COMPRESSED weist den Client auf ein komprimiertes Ergebnis hin. Die Angabe
.LENGTH=<Zahl> ist die unkomprimierte Längenangabe. Sie ermöglicht dem Client, den für das Auspacken bereitzustellenden Speicherplatz abzuschätzen.
Als Kompressionswerkzeug wird die Funktion compress() aus der im Quellcode frei verfügbaren Softwarebibliotek ZLIB (http://www.cdrom.com/pub/infozip/zlib/) eingesetzt.
Es existieren ZLIB-Module für viele Programmier- und Interpretersprachen (z.B. C, Dephi, Basic, Perl, Python, ...).
Der Client packt das komprimierte Ergebnis mit der ZLIB-Funktion umcompress() aus.
Umgekehrt ist auch avantiin der Lage, einen komprimierten Auftrag entgegenzunehmen. Avanti wird dann das Ergebnis immer komprimiert versenden. Ein compress-Befehl ist nicht mehr nötig.
Die optionale Sequenz ZLIB:END_COMPRESSED wird bei der Auftragsannahme als Ende-Zeichen des Kompressionsteils gewertet.
Fehlt diese Angabe wird davon ausgegangen, daß alle Zeichen nach der Startsequenz in komprimierter Form vorliegen.
HINWEIS: Das komprimierte Ergebnis ist im Umfang durch die die Größe des eingestellten Ergebnisspeichers (default: 100kb)begrenzt.