`Register`

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 einer Skript-Sprache. Der Server kann diese Befehle ausführen. Aus dieser ursprünglichen avanti-Skriptsprache ist die `FLEX`-Sprache des Windows-Programms a99/alcarta 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	acon: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(). Diese ist auch in a35ini.php enthalten, welche die Einstellungen für die a35-Oberfläche enthält.

Die Zeilen 2 bis 4 sind die eigentlichen Anweisungen, die an der Datenbank ausgeführt werden sollen. 

Für avanti (d.h. für 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 acon-Sonderbefehle

Auch der Befehl `list` ist auf acon beschränkt, wird aber in einem eigenen Text beschrieben. 

@ DB=datenbank ID=user/PASSWORD	
	Zugriffs-Steuerzeile am Ende des Auftrags. 
	Da der avanti-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
acon 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 seit 2014 
acon 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 acon in der Lage, einen komprimierten Auftrag entgegenzunehmen. acon 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. 

?Register=h xa 
?list=h xlist 
?Sonderbefehle=h =Es folgen 
?Fehlermeldungen=h =Fehlerbedingungen 
?FLEX=h flex 
?phpac=h phpac 
?acon=h acon