WWW-Anbindung einer allegro-Datenbank 
 
`Übersicht der PHP-Dateien für RuckZuck`   `Aufbau von PHP-Dateien` 
 
Achtung: Ab 17.3.2003 umgestellt auf `Unicode.` Aber nur für die Web-Oberfläche, d.h. die Datenbank selbst braucht nicht mit Unicode zu arbeiten!
 
Für den avanti-Server gibt es eine eigene `Installationsanleitung`und weiteres Material!

Hinweis:  
Ab 2013 wird eine Oberfläche `a35`angeboten, die auf HTML5, CSS3 und PHP aufsetzt und auch in einer Variante für Mobilgeräte existiert. 

Installationsvoraussetzungen 
1. 
Die Grund- oder Demo-Installation geht davon aus, daß der avanti-Server für Windows auf derselben Maschine installiert ist, auf dem auch, auf einem eigenen Verzeichnis, die Demo-Datenbank liegt. Der Pfad der Datenbank muß dem Server über die Datei  avanti.con  bekanntgemacht werden, die normalerweise im selben Ordner liegt, in dem sich auch das Programm  avanti  befindet. Das Muster dafür ist die Eintragung für die DemoBank (unter UNIX/Linux ist die Pfadangabe entsprechend anders): 

[avdemo] 
directory = c:\allegro\ademo2 
access = 3 
konfiguration = a 
indexparameter = cat 
opac = OPAC:0 
admin = AVANTI:3 
master = ALLEGRO:2 

Nachdem man dies eingerichtet hat, avanti neu starten (Windows: Dienstprogramm stoppen und starten), denn dann liest es die Datei avanti.con.

2. 
Ein Web-Server muß sowieso installiert sein. Am einfachsten ist die Installation des Apache-Servers mit dem bekannten, kostenlosen XAMPP-Paket, leicht im Web zu finden. Für denjenigen, der mit Windows 2000 arbeitet, liegt es nahe, den latent darin bereits vorhandenen IIS-Web-Server in Bereitschaft zu versetzen; man kann sich dann die Installation eines zusätzlichen Web-Servers ersparen.
 
Ferner muß  PHP 5.x installiert worden sein (vom Netz heruntergeladen, Quelle: http://www.php.net ). Achtung: bei der Installation darauf achten, daß PHP mit dem "richtigen" Web-Server (Apache, Xitami, IIS, ...) "verbunden" wird! 
In der Konfigurationsdatei php.ini den Wert  register_globals=off setzen (ist default). 
 
Der avanti-Server muß, wie gesagt, auf der Maschine laufen, wo die Datenbank liegt! Der Webserver kann auf einer anderen laufen. Die IP-Adresse der avanti-Maschine muß in der Datei av_ini.php stehen (siehe unten). Die PHP-Skripte nehmen die Verbindung mit dem avanti-Server über TCP/IP auf. 

Wohin mit den Dateien? 
Achtung: Alle Dateinamen müssen komplett in Kleinbuchstaben gehalten werden, alle entsprechen dem Namensmodus 8.3, um Probleme beim Hin- und Herkopieren zwischen DOS und UNIX völlig zu vermeiden. Wenn Sie das selbstentpackende Archiv `PHPAC.EXE` öffnen, entpackt es sich und es entstehen drei Unterverzeichnisse: 
 
php:  Zum Webserver!
php- und htm-Dateien und ruckzuck.gif:  
Diese Dateien müssen in ein der Datenbank zugeordnetes Verzeichnis, z.B. ./katalog 
oder k:\apache\xampp\htdocs\katalog am HTM-Verz. des Webservers  (das ist ./htdocs bei Apache, webpages bei Xitami). 
Ersetzen Sie ruckzuck.gif durch eine Grafik eigener Wahl. 
Zu jeder anzubietenden Datenbank muß es ein eigenes Verzeichnis für die Skripte geben! Die PHP-Skripte werden also nicht gemeinsam genutzt, sondern müssen für jede Datenbank als Kopie vorliegen. 
 
param:  Zur Datenbank!
Parameterdateien (.apr, .apt): 
Kopieren in das Verzeichnis, wo die Datenbank liegt (DbDir) und evtl. umbenennen in .xPR für x.CFG (wenn x.CFG statt A.CFG verwendet wird);

doku: 
phpac.rtf: der Text, den Sie eben lesen. Gehört auch zum "Gesamtpaket" des "allegro"-Systems und ist in a99 als Hilfetext les- und druckbar (auf Verzeichnis HELP kopieren, dann  h phpac  eingeben). Außerdem   unicode.rtf  und passwort.txt. 

Einstiegspunkt
Wenn die php- und htm-Dateien (sowie ruckzuck.gif) z.B. auf  .../htdocs/katalog liegen, ist die Einstiegsadresse von außen z.B. 
http://www.ub.uni-musterstadt.de/katalog/detail.php 
oder (alternativ für die Simpel-Recherche)  
http://www.ub.uni-musterstadt.de/katalog/ 
dann wird  index.htm  aufgerufen (die man im übrigen frei gestalten kann). 
 
Einstieg "von innen", also auf dem eigenen Rechner, (geht auch, ohne mit dem Internet überhaupt verbunden zu sein): 
 
http://127.0.0.1/katalog/detail.php 
oder - alternativ für die Simpel-Recherche -  
http://127.0.0.1/katalog/ 
und statt 127.0.0.1 kann man auch localhost schreiben.
 
Mehr zu den Dateien, und was damit zu tun ist 
 
PHP-Dateien 
Diese müssen auf ein eigenes Unterverzeichnis unter dem Dokumentenverzeichnis des Web-Servers. 
Startseite ist  index.htm oder detail.php, einstellbar in av_ini.php. 
In  av_ini.php  liegen die Variablen mit Anpassungsbedarf: das sind hauptsächlich IP-Nr. des avanti-Servers (Hinweis: avanti kann auf einer anderen Maschine laufen! Wenn nicht, dann ist es die 127.0.0.1), Datenbankname, Username, Passwort, Titel, und einige weitere Angaben, wie $Startpage, $TI ....  
Ferner enthält  av_ini.php  ein paar Unterprogramme, und zwar diejenigen, die man für jeden Job braucht. Dies erspart es, noch eine weitere Datei einbinden zu müssen. 
Hat man mehrere Datenbanken anzubinden, kopiert man die Dateien alle jeweils auf ein eigenes Unterverzeichnis. 
Das kann man auch tun, wenn man mehrere verschiedenartige Zugänge zur selben Datenbank einrichten will. 
 
Die Dateien mit dem Präfix  av_  sind unselbständig, sie werden bei Bedarf von anderen Dateien nachgeladen. 
Rot sind die Namen der Dateien, in die man evtl. eingreifen muß. Darin stehen Kommentare! Die anderen kann man bei Erscheinen einer neuen Version jeweils unverändert übernehmen! 
 
av_ini.php   	Einstellungen und Grundfunktionen für die betreffende Datenbank,  
	sozusagen die INI-Datei für einen bestimmten Zugang. Ferner: CSS (Style Sheet)  
	zu ändern u.a.: $DB, $ID, $Server, $Port, $Dispar, $CW, $RESULT, $ShortDisp 
index.htm     	Startseite in schlichter Form (Angebot: Link zu detail.php). Freie Gestaltung! 
detail.php   	Startseite für Detailsuche, ruft dann auf (wenn der Nutzer etwas eingegeben hat): 
detail.job   	wird von  detail.php  gestartet und macht die eigentliche Arbeit
find.php       	Ausführen einer Detailsuche, startet sofort eine der beiden folgenden: 
page.php         	   Anzeige eines Registerabschnitts, startet nach einem Klick des Nutzers rset.php : 
rset.php         	   Anzeige einer Ergebnismenge, startet nach einem Klick des Nutzers grec.php : 
liste.php         	   Alternative zu rset.php mit Kästchen zum Markieren 
grec.php           	Anzeigen eines Datensatzes (Get Record). Nach Klick auf "Bearbeiten" startet edrec 
grex.php           	   dasselbe, Version für Einträge mit 1 Treffer im Register
ajax3.php           	Universalskript, mit dem man beliebige Jobdateien (*.job) starten kann: 
	(dazu gehören noch  ajax3.js  und  ajax3.ini )

(Die folgenden drei werden nur gebraucht, wenn Schreibfunktionen angeboten werden sollen) 
edrec.php            	Bereitstellen eines Satzes zum Editieren, oder leeres Formular für neuen Satz, 
 	     startet dann write.php bei Klick auf "Speichern" 
write.php       	  Speichern des bearbeiteten oder neuen Satzes (Passwort-Methodik!) 
del.php	Löschen eines Satzes (Passwort!)  [startet aus grec.php bei Klick auf "Löschen"] 

Die folgenden werden automatisch eingebunden: (keine Modifikation nötig) 
av_page.php 	Kernfunktion für  page.php  (Aufbereiten einer Registerseite samt Blätterfunktionen etc.) 
av_rset.php   	... für rset.php (Aufbereiten einer Portion der Kurzliste) 
av_list.php   	... für liste.php (Alternative zu av_rset.php) 
glist.php   	... wird aus av_list.php aufgerufen, um die markierten Sätze zu zeigen 
av_grec.php   	... für grec.php  (Holen und Anzeigen eines Datensatzes) 

Für die Schreibfunktionen muß man vor allem in edrec.php und write.php eingreifen. Die Stellen sind markiert durch xxx. Es geht um die Kategorien, die in eigenen Edit-Feldern angeboten werden sollen. 
Dafür ist bereits eine gewisse Flexibilität in einem Unterprogramm von edrec.php verpackt, damit man es relativ leicht hat, das Formular selber zu gestalten: man muß nur ein einfaches Muster kopieren und seine eigenen Feldnummern einsetzen. 
Im Paket gibt es außerdem noch: 
tellme.htm	Hier nur als Muster für eine Informationsdatei zur Datenbank. Die kann jeder gestalten, wie er will. Aufruf z.B. aus index.htm 

Parameterdateien 
Diese müssen in das Datenbankverzeichnis. 
	Für andere Kategoriesysteme, z.B. x.CFG (d.h. wenn Sie nicht A.CFG haben): 
	Die folgenden Dateien kopieren auf *.xpr bzw. *.xpt und entsprechend anpassen. 
	Nur für  $a.cfg gibt es die Datei 
  	d-html.apr	Datensatzanzeige für HTML, angelehnt an d-1.apr 
Muster  für andere CFGs: 
  d-shtm.apr	allgemeine Modelle für die Anzeige: 
	Nur die Dateien `d-s.apt  bzw.  d-k.apt` müssen dann angepaßt werden 
  d-s.apt	wird eingebunden in d-shtm.apr
  d-khtm.apr	In die av_ini.php tragen Sie ein: 
	entweder  $Dispar=d-shtm  oder  $Dispar=d-khtm 
 	s steht für "simpel" und k für "komplex" (d.h. mit verknüpften und hierarchischen Untersätzen. Sie brauchen nur eins von beiden!) 
	Hinweis: die ALFA-Ausleihmethode ist nur in d-khtm eingebaut. 
  d-k.apt	wird eingebunden in d-khtm.apr
  h-php.apr	Kleine Hilfsfunktionen, universell für jede CFG verwendbar. Kopieren auf  h-php.xpr 
  h-edit.apr      	Satz bereitstellen zum Editieren, (kommentiert) 
	Anpassungen nötig: Liste der nicht zum Bearbeiten zugelassenen Felder 
p-brief.apr	Kurzzeilen der Ergebnisliste produzieren (muß angepaßt werden) 
p-liste.apr	Alternative zu p-brief.apr (muß angepaßt werden) 
	(wenn liste.php statt rset.php verwendet wird.) 
 
Die folgenden können einfach kopiert werden auf ad-utf.xpt usw: 
 ad-utf.apt	wird zum Umcodieren ASCII->UTF-8 gebraucht  
	(Achtung: in h-*.apr, p-brief.apr, d-*.apr ) 
 o.apt    	Codiertabelle 1:1 für ASCII -> ANSI, 
	muß mit  to  eingebunden sein in die Indexparameter, 
	ist aber für PHP nicht wichtig, sondern nur für a99! 
 d-htm.apt    	einige HTML-Tags (Schrift, Farben) 
 ucodes.apt    	Umwandlung UTF-8 -> ASCII. Einbauen in Indexparameter, 
	wenn intern NICHT  Unicode verwendet wird, sondern ASCII  (also im Normalfall), 
	d.h. dort den Befehl  tucodes  einsetzen. 
Die letzte Datei ist wichtig für das Editieren und für das Umwandeln der Nutzereingabe (wenn z.B. 'Müller' eingetippt wird), weil diese immer in UTF-8 codiert ist. 
 
Wichtiger Hinweis: 
In den Indexparametern (Standard: cat.api) muß es Zeilen für die Registerüberschriften (beginnen mit |1..., |2... ) und für die symbolischen  Registernamen wie PER oder TIT (diese Zeilen beginnen mit  I ...) geben. Ebenfalls für Restriktionen (beginnen mit R ...), wenn welche definiert sind. Siehe Handbuch S. 179 u. 178. Die symbolischen Registernamen müssen aus Großbuchstaben bestehen, es können auch Ziffern dabei sein. Beispiele findet man in cat.api

Empfehlungen: 
Wenn man intern ASCII hat (also im Normalfall), dann in die Indexparameter diese Zeile schreiben: 
pa=181 182 183 184 189 190 198 199 207 208 209 210 211 212 219 222 223 232 
damit die Akzentzeichen in UTF-8 korrekt dargestellt werden (hinter dem Buchstaben). 

Ferner in die Indexparameter mindestens diese drei Zeilen einbauen (die dritte nur, wenn intern nicht Unicode verwendet wird): 

u 0 
u 217 217 047 047
tucodes

Tips zur Einbindung in eigene HTML-Seiten etc.: 
Dazu eignen sich vor allem drei Dateien: 
 
page.php   Anzeige eines Registerabschnitts mit Blättern 
                      zu übergeben sind Registername und Startpunkt der Anzeige: 
           z.B.:  page.php?reg=PER&st=shakesp 
 
rset.php   Bildung und Anzeige einer Ergebnismenge 
            mit Blätterfunktionen, Übergabe eines "find-Command": 
            z.B.:  rset.php?ufC=PER+shakesp%%3F 
 
grec.php   Holen und Zeigen eines Satzes 
           z.B.:  grec.php?urN=12345   // Zeige Satz Nr. 12345 
           oder   grec.php?urG=NUM&urS=12345678 
           (Satz mit Eintrag 12345678 im Register NUM) 
 
edrec.php   Einen Satz zur Bearbeitung bereitstellen 
           z.B.:  edrec.php?urN=12345   // Bringe Satz Nr. 12345 ins Bearbeitungsformular 
	Ohne Satznummer: Leeres Formular für neuen Satz bereitstellen. 

Die eigentlichen Funktionen sind ausgelagert in die Dateien av_page.php, av_rset.php und av_grec.php  
So bleibt die Anwendung übersichtlich. Für die eigene Gestaltung muß man sich nur die oben genannten drei Dateien vornehmen, die av-Dateien werden nur eingebunden mit z.B. dem Befehl 
include_once("av_grec.php")  
Die Variablennamen stehen in Beziehung zu internen Variablen (#u-Variable) von "avanti" und sind daher immer von der Form  uxY mit einem Kleinbuchstaben x und einem Grossbuchstaben Y. 
Die wichtigsten sind: 
 urG   Registername, z.B. PER 
 urS   Register-Startpunkt, z.B.  shakesp 
 ufC   find command, z.B.  PER+shakesp%%3F 
 urN   record number (interne Satznummer) 
 urO   Ordnungsmodus, Default a0 (nur in RSET.PHP) 

Wie allgemein üblich, müssen Variablen zur Übergabe an PHP codiert werden, also Leerzeichen durch + ersetzt, ? durch  %%3F usw.  
Die Passwortmethodik für die Schreibfunktionen ist beschrieben in einem zusätzlichen Text: passwort.txt, der auf dem doku-Verzeichnis liegt. Damit hat sich nur der Supervisor zu befassen. 
 
Sonderfunktion "Löschen eines Satzes" 
Das Skript  del.php  kann mit Übergabe einer internen Satznummer gestartet werden: 
.../del.php?n=nummer&uPw=password 
Der Satz mit der betreffenden internen Nummer wird dann gelöscht. 

 
Aufbau einer PHP-Datei 
Das PHP-Konzept hat den Vorteil, daß man Skripte direkt in HTML-Dateien einbauen kann. Bei den Skriptsprachen Perl und Python ist es dagegen so, daß die Skripte eigene Dateien sind, die als CGI-Programme aufgerufen werden. Weil solche Skripte noch dazu auf einem anderen Verzeichnis liegen müssen, wird das Zusammenspiel leicht unübersichtlich. 
Auch aus diesem Grunde hat PHP inzwischen eine hohen Beliebtheit erreicht, und zwar gerade für Datenbankanwendungen.eine allegro-Anbindung mit eigenen Funktionen realisieren will, kann zunächst das Paket PHPac studieren und dann diese Skripte als Vorlagen nutzen.  (Das Archiv phpac.exe liegt auf dem FTP-Server in ac21) 
Hinweis für Perl-Kenner: PHP hat eine große Ähnlichkeit mit Perl. Vermutlich ist das aber eher ein Problem als ein Vorteil, denn es gibt leicht Verwechslungsfehler. Evtl. sind Sie besser bedient mit dem populo-Paket von Thomas Berger. Dieses kommt mit einem einzigen, großen Perl-Skript aus, dessen viele Funktionen durch eigene Befehle aus HTML-Texten heraus aufgerufen werden können - also sehr ähnlich dem PHP-Konzept!  
 
PHP-Dateien, das ist wichtig, werden auf dem Server vorverarbeitet. Der Nutzer, der mit dem Browser eine PHP-Datei aufruft, sieht nicht diese PHP-Datei, sondern erhält einen davon erzeugten HTML-Text, in dem gar kein PHP mehr drin ist, d.h. es erscheint ihm so, als sei es eine statische HTML-Seite! 
Sollen aber Funktionen im Browser des Nutzers ablaufen (also ohne daß erst wieder etwas zum Server geschickt werden muß), z.B. Eingabeprüfungen, so geht das nicht mit PHP (mit Perl und Python auch nicht). Dafür bietet sich nur JavaScript an. In den Skripten rset.php und edrec.php sind Beispiele zu sehen. 
 
Nachfolgend ist zum besseren Verständnis der PHPac-Skripte das allgemeine Schema einer PHP-Datei mit eingebautem avanti-Job dargestellt. Zur Verdeutlichung der unterschiedlichen Anteile werden hier Farben benutzt: 
 
BLAU = HTML 
GRÜN = PHP 
LILA = Javascript 
ROT = FLEX 
GRAU = Kommentar 
 
PHP-Datei, allgemeines Schema
Nochmals: Eine solche Datei bekommt der Endnutzer nicht zu sehen, wenn er im Browser die "Source" betrachtet! Er sieht vielmehr statt der PHP-Teile das, was bei der Ausführung der PHP-Befehle vorher auf dem Server entstanden ist. Besonders der PHP-Befehl "echo" ist dazu da, Texte auszugeben, die dann sichtbar werden. JavaScript ist dagegen voll sichtbar, wenn man es nicht in eine Datei vom Typ .js auslagert. 
 
<HTML> 
<HEAD> 
<!--  Kommentar  --> 
<TITLE> 
 Titel der Seite, evtl. hier auch PHP Befehle zur Erzeugung eines variablen Titels! 
 (erscheint im Browser als Überschrift) 
</TITLE> 
  Optional: 
<script language="JavaScript"> 
//  Javascript-Funktionen 
... 
</script> 
 
</HEAD> 
 
<BODY> 
<!--   beliebiger HTML-Text --> 
 
<?php 
   // hier beginnt ein PHP-Programm-Abschnitt 
include_once("av_ini.php"); 
    // da steckt die Funktion  sendjob()  drin, ferner die Angaben zur Datenbank! 
 
 // beliebige PHP-Befehle 
 
$job = array(    // Beginn eines eingebauten avanti-Jobs = FLEX 
 
"FLEX-Befehl", 
"FLEX-Befehl", 
//   wenn innerhalb eines FLEX-Befehls ein " oder \ vorkommt, muß man \" bzw. \\ schreiben! 
//  Jede FLEX-Zeile muß in "..." eingeschlossen sein und mit Komma (bis auf die letzte) enden 
//  Wenn ein " innerhalb einer FLEX-Zeile vorkommen muß, dann \" schreiben
//  Empfehlung: in var- und write-Befehlen besser ' statt " verwenden, wo immer möglich 
... 
"FLEX-Befehl" 
);               // ENDE des FLEX 
 
//  beliebiger weiterer PHP-Text 
 
// Job an avanti senden (Funktion steckt in av_ini.php) 
$k = sendjob($Server, $Port, $job, $erg); 
 
// $k = Anzahl Zeilen der Ausgabe, d.h. Elemente von $erg 
 
// Alternative 1: 
// Ergebnisse (Elemente von $erg )  einfach nur anzeigen 
av_out($erg); 
//  Funktion ebenfalls av_ini.php, dadurch wird daraus HTML-Text! 
 
// Alternative 2: 
// Ergebnisse, d.h. array  $erg[ ]  mit PHP auswerten, dabei verwendet man 
//  echo ...  und   printf...   zur Produktion von HTML-Text 
 
?>    ENDE des PHP-Jobs 
 
      beliebige weitere HTML- und PHP-Teile oder auch JavaScript 
 
</BODY> 
</HTML> 
  
BEISPIELE

Datei ask.htm (Diese startet dann die Datei show.php) 
<! Minimale Startdatei zum Testen: Abfrage einer Nummer vom Nutzer> 
<html> 
<head> 
<title>Test HTM-PHP</title> 
</head> 
<body> 
<h1>Welcher Satz?</h1> 

<form name="frage" action="show.php" method="get"> 
Bitte die Satznummer: 
<input name="num" type="text"> 
</form> 
<! Es wird dann show.php aufgerufen und $num enthaelt dort 
     die eingegebene Nummer> 
</body> 
</html>
 
Datei show.php
<! Minimale Jobdatei zum Testen: Finden und anzeigen> 
<! Aufruf aus dem Formular von ask.htm> 
<html> 
<head> 
<meta http-equiv="content-type" content="text/html; charset=UTF-8"> 
<?php 
  include_once("av_ini.php");  // Einstellungen, Grundfunktionen 
echo "<title>"; 
  echo $TI ; 
echo "</title>"; 
?> 
</head> 
<body> 
<h1>TESTJOB</h1> 
<?php 
// $num wurde von ask.htm uebergeben 
// Job fuer avanti zusammenstellen: 
$job = array( 
              // FLEX-Befehle  ****************************** 
"var '#$num'", 
     // wenn z.B. 123 eingegeben wurde, wird jetzt der 
     // Befehl  find #123  gegeben, denn 123 wurde in $num übergeben: 
"find", 
"if error jump err", 
"xport p p-unicod", 
"dow a", 
"dow wX", 
"wri 'Start' n", 
"wri 'Nummer: ' #nr '<br>IdNr.: ' #00 '<br>'", 
"wri 'Titel: ' #20 '<br>Verf.: ' #40 '<br>E.-Jahr: ' #76 '<br>'", 
"wri 'Kommentar: <br>' #81 n", 
"dow A", 
"end", 
":err", 
"wri 'Satz mit der Nummer $num existiert nicht<br>'" 
    // Ende der FLEX-Befehle ********************** 
); 
// Job senden (jetzt enthalten in der Variablen $job) 
$k = sendjob($Server, $Port, $job, $output); 
// Ergebnisse stehen in $output, anzeigen 
av_out($output); 
?> 
</body> 
</html> 

?Übersicht der PHP-Dateien für RuckZuck=h =Die Dateien 
?d-s.apt  bzw.  d-k.apt=x help vb154`help =Muster 
?Aufbau von PHP-Dateien=h =Aufbau einer PHP-Datei 
?Unicode.=h unicode 
?PHPAC.EXE=~start http://ftp.allegro-c.de/ac21/avanti-w/phpac.exe 
?Installationsanleitung=~start http://www.allegro-c.de/doku/avanti 
?a35=~start http://www.allegro-b.de