verwendete Notationen:
abc kennzeichnet einen festen (Variablen-)Namen
(z. B. JobTyp ) (nicht mit dem Inhalt der Variablen
zu verwechseln)
Zur Kenntlichmachung von populo-Sprachelementen dienen die Zeichenfolgen
PO!…!
PO&…&
PO?…?
.job-Dateien noch die Zeichenfolge
PO:…:
Die Konstruktionen PO&…& und PO?…? müssen jeweils
in einer eigenen Zeile stehen, da alles außerhalb dieser Zeichenfolgen
ignoriert wird. Insbesondere sollten diese Zeilen keine weiteren relevanten
Informationen enthalten! (Kommentare sind hingegen möglich.)
Bei allen Sprachelementen sind zwischen PO!…! und PO:…: dürfen
das jeweilige Begrenzungszeichen (PO&…& oder PO?…? darf das jeweilige
Begrenzungszeichen (
Variable enthalten stets Zeichenketten, die jedoch auch als
Wahrheitswerte (
populo kennt zwei verschiedene Arten von Variablen: neben den
üblichen, einfachen Variablen (Skalare) gibt es indizierte Variable.
Während ein Index von Variablen in anderen Programmiersprachen häufig
innerhalb irgendeiner Art von Klammern angegeben wird, sieht dies bei
populo etwas anders aus:
Der Index wird mit Unterstrich Localize,
aber auch bei den Kontrollstrukturen STRUC und LOOP.
Beide Arten von Variablen sollten nicht mit den von populo selbst
verwendeten (Perl-)Variablen oder den Namen der HTTP-Felder
verwechselt werden.
Gültige Namen von Variablen dürfen nur aus Buchstaben (allerdings ohne Umlaute) und Ziffern bestehen. Außerdem müssen sie immer mit einem Großbuchstaben beginnen.
populo-Strukturen bieten die Möglichkeit, ähnlich einer Liste
inhaltlich zusammengehörende Information in ihrem Zusammenhang zu
belassen.
Perl-intern sind sie als sogenannte Hashes realisiert, d. h. durch Zeichenketten („Schlüssel“) indizierte Listen. Sie werden entweder direkt innerhalb der datenbankspezifischen Db.pl oder mit Befehlen von populo selbst definiert. Ihr Aufbau ist
%Struktur = (
'#Default#' => Defaultschlüssel,
'#Labels#' => [Label1, Label2, …],
Schlüssel1 => [Wert11, Wert12, …],
Schlüssel2 => [Wert21, Wert22, …],
.
.
.
);
Die Zeilen mit #Default# und #Labels# sind optional,
während der Laufzeit von populo wird meist noch ein weiterer Schlüssel
#Labelsnr# hinzugefügt.
Die eckigen Klammern
Der Spezialschlüssel #Default# gibt eine Vorzugsauswahl an,
die in der Routine IniVar und bei der Kontrollstruktur
STRUC berücksichtigt wird.
Der Schlüssel #Labels# enthält Namen für die einzelnen Elemente der
Wertelisten, die die Routine Localize benutzt, um die entsprechenden
Einträge wieder zugänglich zu machen.
Alle Label und der Name der Struktur selbst müssen den Regeln für gültige Variablennamen entsprechen (vgl. den Abschnitt Variablen), insbesondere müssen sie mit Großbuchstaben beginnen!
Der Name Struktur darf nur einmal vorkommen, insbesondere darf es auch keine gleichnamige Variable geben. Schlüssel und Label dürfen innerhalb einer Struktur nur einmal, Werte natürlich mehrfach auftreten.
Zu Strukturen gehört fast immer ein oder mehrere in der Konfigurationsdatei als Perl-Array anzugebende Indexsysteme, die eine Vorzugsreihenfolge der Schlüssel angeben, z. B.
@Reihenfolge = ( Schlüssel1, Schlüssel2, …);Indexsyteme können im Rahmen der populo-Sprache nicht manipuliert werden.
Bemerkung:
In der datenbankspezifischen Datei Db.pl können auch andere
assoziative Vektoren vorkommen, die der hier beschriebenen Syntax nicht
entsprechen müssen, da sie nicht als Strukturen verwendet werden. Ein Beispiel
dafür ist der Vektor %Defaults, der immer definiert sein muß.
Das folgende Beispiel stammt aus der mitgelieferten Datei avdemo.pl:
@CodierKeys = ('html', 'ansi', 'dos'); #ein Indexsystem
%Codierung = ( #Struktur
'#Default#'=> 'html',
'#Labels#' => ['Erlaeuterung', 'Includetabelle'],
html => ['HTML-Codierung', 'd'],
ansi => ['ANSI-Codierung', 'p-ansi'],
dos => ['DOS-Codierung', 'p-dos'],
);
Beim Aufbau eines Formulars wird man die so definierte Struktur
etwa wie folgt einsetzen:
Typischerweise bereits in der Job-Datei wird der Wert des HTTP-Feldes
cod (falls vorhanden) in die Variable SelCodierung
übertragen, sonst der beim #Default#-Schlüssel der Struktur
Codierung angegebene:
//PO&IniVar(SelCodierung,cod,Codierung)&Bei der Ausgabe wird man dann ein Feld mit Radio-Buttons für die Liste der möglichen Codierungen aufbauen:
<FORM ACTION="PO!Pop!" METHOD="POST"> <INPUT TYPE="HIDDEN" NAME="db" VALUE="PO!Db!"> … <!-- PO?STRUC(Codierung, CodierKeys, SelCodierung)? -->Der folgende Abschnitt wird jetzt für jeden Eintrag in CodierKeys durchlaufen, dabei ist der Schlüssel via S_Key zugänglich, die dazugehörige Liste in den Variablen S_Erlaeuterung und S_Includetabelle, entsprechend den Labels
Erlaeuterung
und Includetabelle. Zusätzlich stehen die beiden Wahrheitswerte
S_Select (stimmt der aktuelle Schlüssel mit SelCodierung
überein?) und S_Default (stimmt der aktuelle Schlüssel mit dem
#Default#-Eintrag von Codierung überein?) zur Verfügung.
<!-- PO?IF(S_Default)? kursiv, falls default <i> PO?ENDIF --> <!-- PO?IF(S_Select)? "checked" falls zutreffend <INPUT TYPE="RADIO" NAME="cod" VALUE="PO!S_Key!" CHECKED="yes"> PO?ELSE? --> <INPUT TYPE="RADIO" NAME="cod" VALUE="PO!S_Key!"> <!-- PO?ENDIF? --> PO!Htm(S_Erlaeuterung)! <BR> <!-- PO?IF(S_Default)? kursiv aus nicht vergessen </i> PO?ENDIF --> <!-- PO?ENDSTRUC --> … </FORM>
Funktionen liefern ein Resultat, welches bei Auswertungen anstelle des Funktionsaufrufs eingesetzt wird.
Routinen nehmen mehrere Argumente auf und wirken nur durch ihre Seiteneffekte, d. h. es wird typischerweise eine oder mehrere Variable modifiziert, die vordefiniert sind oder deren Name als Argument übergeben wurde.
Zeilen mit PO&…&-Konstruktionen werden sofort vollständig
entfernt, insbesondere darf stets nur eine solche Konstruktion in
einer Zeile vorliegen.
Wird in .job-Dateien die zweite Form mit
Beispiel: in allegro.job für die Beispieldatenbank gibt es vielfältige Verzweigungen. Welcher Art die von Avanti zurückgelieferte Ausgabe ist, wird erst während der Ausführung des Jobs festgelegt, so daß auch populo dies „durch Avanti“ mitgeteilt werden muß:
// Es folgen Zeilen von Typ 5 = Satznummern write "PO:Set(LineTyp,5):" newline list internal
Kontrollstrukturen bestehen mindestens aus einem ein- und einem ausleitenden Teil.
Zeilen mit PO?…?-Konstruktionen werden sofort vollständig
entfernt, insbesondere darf stets nur eine solche Konstruktion in
einer Zeile vorliegen.
Die Bedingungsprüfungen bei IF und LOOP sind so zu
verstehen:
Hier kann entweder eine Variable (leer vs. nicht leer), eine spezielle
Testfunktion (z. B. CheckMe) oder ein direkter Test eingesetzt
werden. Ein solcher direkter Test besteht aus zwei Argumenten und einem
dazwischenstehenden Vergleichsoperator. Zur Verfügung stehen die aus
Perl stammenden Operatoren
e Expression: Entweder der Name einer Variablen,
eine PO!...!-Konstruktion oder eine Konstante:
Zahlen, in " oder ' eingeschlossene Zeichenketten,
oder frei quotiert, d.h. eingeschlossen in #gotcha#...#gotcha#
wobei gotcha ein frei gewählter String ist.
b Bareword
v Referenz: Name einer PO!...!-Variable
[ Kennzeichen dafuer, dass die folgenden Ausdruecke optional sind
* Es können beliebig viele Argumente vom zuletzt angegebenen Typ folgen
IF und ELSIF
Entspricht einer üblichen if-els(e)if-else-endif-Konstruktion.
Die PO?ELSIF(…)?- und PO?ELSE[…]?-Teile sind
optional.
Die Bedingungen werden nacheinander ausgewertet, bis eine Bedingung
zutrifft. In diesem Fall wird der zugehörige Anweisungsteil
durchgeführt, der Rest übersprungen. Trifft keine Bedingung zu, wird
der optionale Anweisungsteil zwischen ELSE und ENDIF
ausgeführt.
Prototyp: #[e#
Eine Schleifenkonstruktion, die die von Avanti zurückgelieferten Ergebniszeilen verarbeitet (solange Bedingung erfüllt ist).
Die Anweisungen werden für jede der von Avanti
zurückgelieferten Ergebniszeilen durchlaufen. (Ist Bedingung
angegeben, nur solange, wie Bedingung auf die Ergebniszeilen
zutrifft, u. U. also keinmal).
Die Zeilen waren bereits beim Empfangen aufbereitet und verschiedenen
Typen zugeordnet worden, jetzt liegt diese Zuweisung in der Variablen
LineTyp für Tests bereit, die Inhalte der Zeilen verhalten sich
wie eine nach L_ lokalisierte Struktur, handelt es
sich etwa um Registerzeilen oder Kurztiteleinträge, so enthält
L_Recnums die Satznummer,
L_0, L_1 etc. enthalten die von den im
datenbankspezifischen Perlscript definierten Hooks
&ParseRegisterLine ( (cf.)) und
&ParseSTLentry ( (cf.)) aufbereiteten Zeilen
des Resultats von Avanti.
Eine Schleifenkonstruktion über bestimmte Schlüssel der Struktur.
Für jeden Schlüssel aus Indexsystem wird Struktur nach
Shortcut (falls nicht angegeben: S_)
lokalisiert und die Zeilen ausgewertet.
Ist der aktuelle Schlüssel identisch mit dem in der optionalen Auswahl
angegebenen, so ist S_Select wahr;
stimmt er mit dem im Spezialschlüssel #Default# von Struktur
spezifizierten überein, so ist S_Default wahr.
Der aktuell durchlaufene Eintrag von Indexsystem ist als
S_Key zugänglich.
Eine allgemeine Schleifenkonstruktion mit Bedingungsprüfung.
Solange Bedingung erfüllt ist, werden die Zeilen wiederholt.
Zu fast jedem (gültigen) JobTyp gehören die
(JobTyp-spezifischen) Dateien JobTyp.job und
JobTyp.htm.
JobTyp.job soll eine korrekte
Jobdatei für Avanti sein, allerdings ohne die festen Zeilen
&Aufrufpfadam Anfang und
@ DB=Datenbank ID=User/Password AVANTI:EOJam Ende, die automatisch von populo generiert werden.
JobTyp.htm ist eine korrekte HTML-Datei, insbesondere ohne die Bestandteile
Content-type: text/html <Leerzeile>des HTTP-Headers.
Zusätzlich können beide Dateien eine Reihe von Variablen und Befehlen
enthalten, die den konkreten Programmablauf steuern. Variablen und
Funktionen können dabei direkt im jeweiligen Text stehen, Routinen
und sonstige Steuerbefehle sollten dateispezifisch auskommentiert
sein (also mit
Eine Anfrage wird nun wie folgt bearbeitet:
db
wird ausgewertet und in die Variable Db überführt.
t_… bestimmt.
$pathpraefix
wird die zugehörige Templatedatei JobTyp.pl geöffnet.
PO:…:-Konstruktionen aufgelöst oder
entsprechend den deklarierten LineTypen und den im
Perl-Hash %LineFlow benannten Routinen vorverarbeitet.
LI:-Notation) aufzubereiten.
LOOP-Konstruktionen
aufgebraucht.
Emuliert Avanti-Ausgabe.
Inhalt wird in das Resultat als Zeile vom Typ LineTyp eingefügt.
Beispiel: Beim Blättern in Ergebnismengen wird direkt auf die
Kurztitelliste zugegriffen, dabei kommt es nur darauf an,
nach dem Aufruf von Paginate den Teilbereich der Satznummern,
wie er in P_Recno enthalten ist, so unterzubringen, daß
später automatisch die Kurztiteleinträge geholt werden.
Nach Ausführung etwa von
//PO&Paginate(PageNo,MaxShowResult,JobSubtyp,Recnums)&sind dabei äquivalent:
find #PO!P_Recno! write "PO:Set(LineTyp,3):" newline list recnumbzw.
find #PO!P_Recno! write "PO:Set(LineTyp,13):" newline list internalund
//PO&AddResult(13, P_Recno)&
wandelt das Argument von ASCII nach HTML (7-bittig) um.
…etwa weil man die Konfigurationsdateien unbedingt mit DOS-Umlauten beschicken möchte… Für ANSI-Werte siehe (cf.).
Hängt an den Wert von Variable die Ergebnisse der Auswertungen
der Werte durch POeval an (alles nur Zeichenketten).
Gab es Variable noch nicht, wird sie vorher mit
Weist Variable das Ergebnis der Auswertung von Wert durch
POeval zu.
Beschreibung siehe (cf.).
Für die in der Variablen aufgeführten Errorcodes von Avanti wird der Text bis zum ersten Doppelpunkt durch den angegebenen Text ersetzt.
IP-Nummer oder DNS-Name des zu befragenden Avanti-Servers.
Portnummer des zu befragenden Avanti-Servers.
Ist (eine der Satznummern aus) Testvorrat in Nummernvorrat enthalten?
Liefert den Rückgabewert
Einsatz typischerweise in den Bedingungs-Argumenten von Kontrollstrukturen.
Ist Teststring in Zeichenfolge enthalten?
Im Prinzip obsolet, da IF-Konstruktionen Zeichenkettenvergleiche mittels regulärer Ausdrücke erlauben.
Liefert den Rückgabewert
Einsatz typischerweise in den Bedingungs-Argumenten von Kontrollstrukturen.
Faßt bestimmte an populo übergebene Parameter (HTTP-Felder) in einer Struktur zusammen.
Erzeugt in der Struktur Struktur zu allen HTTP-Feldern, die mit feldmuster beginnen, Schlüssel mit dem Namen des HTTP-Feldes ohne den Anfang feldmuster. Der Wert des jeweiligen HTTP-Feldes wird diesem neuen Schlüssel als Wert zugewiesen.
Gab es die Labels Key und Label noch nicht, so werden sie
an eine bestehende Liste zu #Labels# angehängt. Gab es den
Schlüssel #Labels# noch nicht, so wird einer initialisiert.
Gab es die Struktur Struktur noch nicht, so wird sie hiermit
erzeugt (wohl der Normalfall).
Beispiel: Ein Abfrageformular stellte fünf Eingabefelder
zur Verfügung mit jeweils einem korrespondierenden Pulldown-Menue,
in dem der Benutzer den „Typ“ seiner Eingabe auswählen kann.
Diese Felder haben im Formular die Namen
@IndexSystem = ('1', '2', '3', '4', '5');
in der Konfigurationsdatei.
Die folgende Jobdatei sammelt diese Informationen dann wie folgt ein:
//PO&Collect(Eingabe,text_,Begriff)& //PO&Collect(Eingabe,pull_,Register)&und später kann dann so darauf zugegriffen werden:
Gesucht werden soll: PO?STRUC(Eingabe,IndexSystem)? PO!S_Begriff! aus Index PO!S_Register! PO?ENDSTRUC?
Setzt die Suchanfrage für Avanti zusammen.
Aus der Struktur Query mit Indexsystem QueryNummern wird
entsprechend der gewählten Verknüpfungs-Logik und dem
Trunkierungszeichen eine Suchanfrage für Avanti zusammengesetzt
(als Rückgabewert dieses Befehls).
Suchbegriffe, zugehöriges Register, Verknüpfungslogik und die
Trunkierung können vorher noch durch in der in Db.pl im Hash
MaskenSpecial angegebene Unterprogramme modifiziert
werden. Die modifizierten Suchbegriffe werden in der Struktur
Query unter dem jeweiligen Schlüssel unter dem Label
Query gespeichert.
Vor der Ausgabe wird durch PrintHeader der HTTP-Content-Type
angegeben. Belegen von ContentType gibt statt des Defaults
Content-type: ContentType Leerzeile
printf(3)-Template für das Datumsformat in Modified
( (cf.)) und DbTime ( (cf.)).
Db dient zur Identifikation der Datenbank
und wird automatisch von populo aus dem Namen des Konfigurationsskripts
oder dem HTTP-Feld db bestimmt.
DbSubmitted dient zur Identifikation der Datenbank
und wird automatisch von populo aus dem HTTP-Feld db oder aus
Db ( (cf.)) bestimmt.
Tip: Wenn Sie eine separate Datenbank haben, die regelmäßig aktualisiert
wird, können Sie nach dem Auflegen der neuen Datenbank den
Datumsstempel der .pl-Datei mit
touch -r Pfad/Db.TBL Db.plauf den der Datenbank setzen. In den
.htm-Templates können Sie
dann mit PO!DbTime! stets das „Datum der Datenbank“ einblenden.
Falls gesetzt, werden diagnostische Meldungen aus den Kategorien
entsprechend WantDebug ( (cf.)) ausgeben.
Eine Beschreibung der definierten Konfigurationsklassen findet sich im Abschnitt (cf.) über Debugmöglichkeiten.
Die angegebenen Variablen werden eingeführt. Wichtig ist dies vor Schleifenkonstruktionen, da bei Variablen, die nur innerhalb von Schleifen vorkommen, die Heuristik die Variablennamen fälschlich als Texte erkennt (auf Meldungen Scalar failure achten).
Erniedrigt den (ganzzahligen) Wert von Argument um 1.
Dies ist nützlich für einfache Arithmetik, etwa bei Jahreszahlenbereichen
für Suchbegriffe. Avanti versteht aber inzwischen auch
Falls sich aus Bereich eine (vierstellige) Jahreszahl als
„Endejahr“ identifizieren läßt, wird diese mit vorangesetztem
Präfixtext sowie Operator (
Korrespondiert zu StartRes ( (cf.)).
Nützlich, falls Jahreszahlenbereiche in einem Feld einzugeben
sind, aber zwei Restriktionen ergeben sollen.
Beispiel bei (cf.).
Zugriff auf Environment
Gibt den Inhalt der Environmentvariablen Environmentvariable
zurück, falls diese belegt ist, sonst
Alle Eingabewerte in URL-encodierter Form (auch wenn ursprünglich als Formular mittels POST übertragen oder interaktiv erfragt), mit Ausnahme der Felder, deren Namen als Argumente aufgeführt sind.
Vorsicht: Dies mag für manche Server oder Browser viel zu lang sein.
In einem gewissen Sinn ist die Funktion Everything komplementär zur Routine LinkIni ( (cf.)).
sortierte Liste der Satznummern, zu denen noch keine Kurztitelzeilen zwischengespeichert sind (Argument <Force> = 0), bzw. aller Satznummern zu Kurztitelzeilen (Argument <Force> = 1).
Eingelesene Kurztiteleinträge werden intern zwischengespeichert.
<Zeitoffset> ist dabei eine Folge von positiven oder negativen ganzen
Zahlen mit angehängtem
Gibt eine Zeitangabe nach RFC 1123 zurück, die um <Zeitoffset> in der Zukunft liegt.
Beispiel: Folgender Code produziert einen Expires-Header, der „Gültigkeit 23 Stunden ab Absenden“ besagt:
<META HTTP-EQUIV="expires" CONTENT="PO!Future(+1D -1h)!">
Auswertung von HTTP_USER_AGENT.
Gibt einen Namen für den benutzten Browsers zurück, falls dieser identifiziert werden konnte (z. Z. nur 'Internet Explorer' und 'Netscape').
Allegro-Satznummern verarbeiten
Bereitet die Datensatznummern aus dem HTTP-Feld feld (und der
optionalen Angabe in Extra) für populo-interne Bedürfnisse auf
und weist sie der Variablen Variable zu. Die Anzahl erhaltener
Datensatznummern wird in der Variablen Variablenum
hinterlegt (die vorher vom Anwender deklariert werden muß).
wandelt das Argument von ANSI nach HTML (7-bittig) um.
Vgl. AHtm ( (cf.)) für ASCII-Werte.
Erhöht den (ganzzahligen) Wert von Argument um 1.
Dies ist nützlich für einfache Arithmetik, etwa bei Jahreszahlenbereichen
für Suchbegriffe. Avanti versteht aber inzwischen auch
Nur falls Variable noch nicht mit einem Wert belegt ist:
Sorgt für die Initialisierung einer benötigten Variable aus dem HTTP-Feld feld, notfalls mit einem geeigneten Default-Wert.
Die Routine versucht, der Variable einen der folgenden Werte zuzuweisen (in dieser Reihenfolge) (5):
#Default#-Wert der Struktur Struktur
%Defaults
Zugriff auf Eingabe
Gibt den Inhalt des Eingabefelds HTTP-Feld zurück, falls diese
belegt ist, sonst das Default aus der Konfigurationsdatei, sonst
wandelt das Argument in eine ganze Zahl um
Insbesondere werden führende Nullen entfernt.
wandelt das Argument von Ostwest-Windows nach ISO 8859-1 um.
Vgl. (cf.) für gleichzeitiges Konvertieren nach HTML.
Der Wert von JobTyp wird aus den HTTP-Feldern bestimmt, die
mit
Kommt ein Feld t_Text1_Text2=Wert vor,
so wird Text1 der Variablen JobTyp und Text2 der
Variablen JobSubtyp und zugewiesen. Danach erfolgt die
weitere Ausführung mit der (datenbankspezifischen) Jobdatei
JobTyp.job.
Während der Vorverarbeitung der Job-Datei oder beim Zurücklesen des
Resulats kann an JobTyp zugewiesen werden, die Präsentation der
Ausgabe erfolgt dann mit der .htm-Datei, die dem aktuellen Wert
von JobTyp entspricht (siehe auch PO!RedoJob!).
Da viele WWW-Browser ein Formular auch dann abschicken, wenn keiner der Submit-Knöpfe vom Anwender betätigt wurde, gilt folgende Zusatzregel:
Ein Feld t_Typ mit Wert default oder ignore
wird nur dann berücksichtigt, wenn kein anderes Feld t_…
übergeben wurde.
Für Java-Script-Einsatz mit mehr hidden fields gilt folgende Zusatzregel:
Ein Feld t_Typ wird nur dann berücksichtigt,
wenn es einen Wert hat.
Beim Einsatz von graphischen Submit-Buttons werden typischerweise
simultan zwei HTTP-Felder t_Typ.x und t_Typ.y
übergeben, die Suffixe
Folgende reservierte JobTypen dienen zum Abfangen von Fehlerzuständen:
Alle diese JobTypen erfordern nur ein Ausgabetemplate (.htm-Datei), kein Jobtemplate JobTyp.job.
Argument für Everything ( (cf.)) im Kontext
von Stat ( (cf.)): Die aufgelisteten HTTP-Felder
werden nicht in die für Auswertungszwecke in den Avanti-Job
codierte Liste der Aufrufparameter integriert.
LOOP-Schleife zugänglich
( (cf.))..
wandelt das Argument in URL-codierte Form um (Als Link).
LineTyp ( (cf.))
werden die von Avanti gelieferten Zeilen durch die hier definierten
Unterprogramme weiterverarbeitet.
Beispiele und Vorbelegung siehe (cf.).
LineTyp dient zur Kennzeichnung der von Avanti
gelieferten Ergebniszeilen entsprechend ihrer Art.
Alle nach der Setzung von Avanti gelieferten Zeilen werden dem jeweiligen Typ zugeordnet.
Vordefiniert sind:
| 0 |
unspezifiziert |
| 1 |
Registerzeile |
| 2 |
Verweisungszeile |
| 3 |
Kurztitelzeile mit Satznummer |
| 4 |
Datenanzeige (expandiert Links) |
| 5 |
interne Satznummern (nicht anzeigen) |
| 6-9 |
frei |
| 11 |
Registerzeile, noch zu expandieren |
| 12 |
Verweisungszeile, noch zu expandieren |
| 13 |
Kurztiteleintrag |
| 14 |
Kurztiteleintrag (nicht anzeigen) |
| 15-19 |
frei (werden expandiert) |
| 21 |
Expandierte Registerzeile |
| 22-30 |
frei |
Beispiel: Während der Bearbeitung der Demo-Datenbank avdemo
ändern sich die Linetypen etwa wie folgt:
| Fluss |
JOB |
->&waitjob |
-> &expandjob |
| acindex |
1 |
-> (1,2) |
|
| acexpand |
11 |
-> (11, 12) |
-> (11[,12]),21 |
| regsrch |
5 |
-> |
-> 21 |
| allegro |
5 |
-> |
-> 21 |
| result |
3 |
-> 21 |
Beschreibung siehe (cf.).
Initialisiert Variable als URL mit den Werten der angegebenen felder (enthält als Beginn den Programmnamen und ist schon korrekt escaped)
Der Inhalt des Schlüssels Schlüssel der Struktur Struktur wird zugänglich gemacht (Ist Schlüssel der Name einer Variablen, wird ihr Wert genommen).
Dabei werden Elemente, für die es eine Entsprechung unter
#Labels# von Struktur gibt, unter dem jeweiligen Namen
aus #Labels# (mit vorangestelltem Shortcut, falls dieser
angegeben wurde) als Variable zugänglich gemacht, alle anderen über
ihre Position (nur falls Shortcut angegeben wurde) (6).
Beispiel:
Es war eine Struktur
%Hallo = ( #Labels#=> ['Name', 'Vorname'], Nachbar => ['Meyer', 'Ernst', 'Universitätsbibliothek', 'Pockelsstr. 3', 'Braunschweig'], Unterbar=> ['Müller', 'Paul', 'Pockelsstr. 5', 'Braunschweig'], );definiert und wir wollen auf die Informationen zu einer bestimmten Person zugreifen:
PO&Set(Wanted, Unterbar)& PO&Localize(Hallo, Wanted, W_)&Danach haben wir Zugriff auf:
Der Name ist PO!W_Vorname! PO!Htm(W_Name)!, die Adresse ist
PO!W_0!
PO!W_1!
PO?IF(W_2)?
PO!W_2!
PO?ENDIF?
was uns die Ausgabe liefert:
Der Name ist Paul Müller, die Adresse ist
Pockelsstr. 5
Braunschweig
Hätten wir im Beispiel den dritten Parameter W_ ausgelassen, hätten
wir nur Zugriff auf die ersten beiden Elemente von Unterbar gehabt,
und zwar mit
PO!Name! und PO!Vorname!
CollectQuery in Abhängigkeit vom symbolischen
Registernamen eigene Hooks für die Aufbereitung von Suchbegriffen
anzugeben. Jeder der durch Komma getrennten Werte muß der Name eines
in der Konfigurationsdatei definierten Hooks sein.
Beispiele siehe (cf.).
Die Werte werden unter der aktuellen Seite in der Reihenfolge ihres Auftretens zusammen mit den von populo generierten Meldungen ausgegeben. Praktisch evtl. für das Debuggen von .job-Dateien.
siehe auch DbTime.
Paginate
( (cf.)).
Paginate unterteilt die durch reorder, first,
previous, next oder last) ergibt.
Shortcut ist optional, wird keiner angegeben, wird als Default
P_ genommen. (Shortcut muß aus einem Großbuchstaben
gefolgt von einem Unterstrich
Nummern muß der Name der Variablen sein, die die durch
Seitengröße muß der Name der Variablen sein, die die maximal zulässige Anzahl anzuzeigender Datensätze pro Ausgabeseite enthält. Diese beiden Werte zusammen bestimmen, welche Datensätze auf welcher Seite anzuzeigen sind.
Ausgangsseite gibt die zuletzt angezeigte Seite an, Aktion wie diese Seitenzahl zu verändern ist:
- vorige Seite (Dekrement)
+ nächste Seite (Inkrement)
Paginate bestimmt nach diesen Angaben:
id=…/…
übertragen.
Ermöglicht die Veränderung (oder Erzeugung) der Struktur.
Schreibt in der Struktur Struktur den Wert Wert in die
Liste zu dem Schlüssel Schlüssel, und zwar an die Stelle, die
Label in der Liste zu dem Spezialschlüssel #Labels#
einnimmt. (Gab es Label noch nicht in der Liste
#Labels#, wird es hinten angehängt. Gab es noch keinen
Spezialschlüssel #Labels#, so wird vorher einer initialisiert.)
Wenn in den Ausgabe-Templates .htm alle URLs mit Bezug auf populo via
<a href="PO!Pop!…"> …</a>gebildet werden, sind diese Seiten immun gegen Umbenennung des Skripts populo.pl, Verlagerung in andere (virtuelle oder reale) Verzeichnisse oder Verlagerung auf einen anderen Server. Wird allerdings mit PATHINFO (cf.) gearbeitet, so expandieren die Browser meistens falsch, und die Referenzen sollten mittels Voranstellung der vollen Pfadangabe PopPath (cf.) erfolgen:
<a href="PO!PopPath!PO!Pop!PO!PathInfo!…"> …</a>
Allegro Avanti Populo Version.
Indexsystem muß der Name einer in der Konfigurationsdatei definierten Liste sein, die Schlüssel zu der Struktur Struktur enthält,
Label1 und Label2 müssen Labels von Struktur sein und tragen die Bedeutung „Register“ und “Suchbegriff“.
Aus den Rohdaten in Struktur werden unter Label2 abgelegte
Suchanfragen zum unter Label1 abgelegten Register aufbereitet
(getrennt). Das Ergebnis wird in einer neuen Struktur Query
hinterlegt.
Query erhält die Labels OrigKey, Register,
Begriff, Treffer, und Query. Jede isolierte
Suchanfrage wird unter einem eigenen Schlüssel hinterlegt und dessen
Rubrik Treffer mit der Anzahl 0, Rubrik Query vorläufig
noch gar nicht initialisiert.
Die erzeugten Schlüssel werden im zugehörigen Indexsystem
QueryNummern, deren Anzahl in der Variablen Querynum
hinterlegt.
Gibt alle Schlüssel / Wertepaare des angegebenen assoziativen Vektors in einer HTML-aufbereiteten Form zurück.
PrepareQuery initialisiert und
von CollectQuery benutzt. Eigene Einträge (etwa in das
Feld Treffer können mit Poke hinzugefügt werden.
RealDb wird vorbesetzt durch den Namen der Datenbank Db bereinigt um eventuelle Ziffern am Ende und kann außerdem durch Setzungen in der Konfigurationsdatei Db überschrieben werden. Diese Variable wird benutzt, um im Job die Datenbank für Avanti anzugeben. Dies dient dazu, (testweise) leicht verschiedene Varianten vorzuhalten, die dieselben Template-Dateien benutzen und sich nur in den Initialisierungen Db.pl unterscheiden.
Recnumsnum enthält die Anzahl der Elemente von Recnums.
Eine Zuweisung an diese Variable ist nicht erlaubt.
Während der Vorverarbeitung der Job-Datei oder beim Zurücklesen des
Resulats kann RedoJob auf JobTyp
entsprechenden .job-Templates wird so erzwungen.
Beschreibung siehe (cf.).
Normalerweise sollte die Vorgabe (von 25) beibehalten werden, außer zum Testen von Kommunikationsproblemen. Da populo jedoch als CGI-Skript nicht persistent ist, gilt diese Nachnutzung der Verbindung nur innerhalb eines Aufrufs des Skripts, nicht darüber hinaus.
Nur in der Form 'ABC:' => 'DEF' hier aufgelistete symbolische
Register ABC werden von LinkEscape ( (cf.))
erkannt, d.h. nur solche Register können von Parameterdateien für
Hyperlinks herangezogen werden.
STRUC-Konstruktion
( (cf.)).
Initialisiert verschiedene Variablen für ein Register.
RegisterStruktur muß die Labels RegStart,
RegEnde enthalten.
Diese Routine ist im Prinzip obsolet, da Avanti inzwischen Pseudoregister transparent behandelt.
Die Routine kann eingesetzt werden, um vor der Recherche in einem
allgemeinen Register den Suchbegriff auf die Registergrenzen (etwa
Die Inhalt des Schlüssels Registerschlüssel der Struktur
RegisterStruktur wird unter den Variablen RegStart,
RegEnde zugänglich gemacht. Außerdem wird
die Variable Suchstring so modifiziert, daß ihr Wert innerhalb
der durch RegStart und RegEnde definierten Grenzen
liegt.
Die Struktur RegisterStruktur muß in Db.pl definiert worden
sein und als Schlüssel die symbolischen Registernamen für Avanti
enthalten sowie folgende #Labels# mit den Bedeutungen:
Beispiel: Sei Register |9I für Avanti symbolisch notiert durch
ISB, so könnte sich dies in der Konfigurationsdatei durch einen
Eintrag
%RegisterStruktur = ( '#Labels#'=> ['RegStart', 'RegEnde'…], … ISB => ['0', '999'…], … );für RegisterStruktur manifestieren. Sinn macht dies aber nur, falls sich im Bereich |9I auch noch nicht-numerische Eintäge (evtl. unter einem anderen symbolischen Registernamen) befinden.
Weist Variable den (konstanten) Wert zu, oder den
Leerstring
Das Timeout Zahl ist keine absolute Schranke für die Bearbeitungszeit, sondern ist eine Setzung für einzelne Teiloperationen: Nur wenn Zahl Sekunden absolut nichts an Avanti geschickt oder von Avanti gelesen werden kann, bricht populo die Verarbeitung ab.
Zu beachten ist, daß Avanti selbst eine Konfigurationseinstellung
für die Maximale Anzahl von Sekunden hat, die ein Job von Anfang
bis Ende seiner Ausführung benötigen darf und daß der WWW-Client
des Benutzers und evtl. der Webserver weitere, eigene Timeouts verwalten.
SocketTimeout ist im Prinzip nur relevant in Situationen,
wo Avanti einen Job abbricht, aber die Verbindung nicht schließt.
Macht zunächst dasselbe wie GetRecnums ( (cf.)),
d.h. in Variable werden Satznummern aus den Feldern feld
und ggfls. der Variablen Extra eingelesen.
Zusätzlich erfolgt ein Vergleich mit der internen Struktur
Thisnums (die beim Einlesen der aktuell gelieferten Datensätze
belegt wurde).
Hierin auch enthaltene Satznummern werden in der Variablen
Variablethis, die anderen in der Variablen
Variableelse hinterlegt. Die jeweiligen Anzahlen sind
unter den Variablen Variablethisnum und
Variableelsenum verfügbar. Alle Hilfsvariablen
müssen vom Anwender vorher deklariert worden sein.
Ist das optionale, vierte Argument Sortnums angegeben,
so werden die Satznummern in Variableelse noch einmal
entsprechend der Nummernreihenfolge in Sortnums
sortiert und aufgespalten in die Nummern Variablepre,
die vor dem ersten Auftreten einer der Nummern in Sortnums
in der Menge Thisnums liegen und in Variablepost
mit den anderen Nummern. Die zusätzlichen Variablen
Variableprenum und Variablepostnum werden
analog besetzt.
Beispiel: In einer Kurztitelliste sollen einzelne Sätze markiert werden können, bei Umsortierungen bleibt die Markierung erhalten, die Anzeige der Markierten Sätze soll entsprechend der aktuellen Sortierung der Kurzliste erfolgen.
Im ersten Job:
// Satznummern aus HTTP-Feld 'recnums' bestimmen PO&GetRecnums(Recnums,recnums)& // Sätze selektieren und sortieren lassen find #PO!Recnums! order … // Anzeige: „Es folgen viele Satznummern“ write "PO:Set(LineTyp,5):" newline list internal // Paginierung ausloesen write "PO:Set(PageNo,1):" newline write "PO:Paginate(PageNo,MaxShowResult,'first',Recnums):" newline // Satznummern nach Avanti füttern und Kurztitel zeigen lassen write "PO:Set(JobTyp,hickup):" newline write "PO:Set(RedoJob,1):" newline
Beim Zurücklesen der durch Avanti sortierten Satznummern wird durch den Aufruf von Paginate ( (cf.)) eine Teilmenge zur „Seite“ 1 bestimmt, in einem zweiten Job (hickup) müssen nun die Kurztitel zu dieser „Seite“ herangeschafft werden:
find #PO!P_Recno! // Anzeige: „Es folgen bekannte Satznummern mit Kurztiteln“ write "PO:Set(LineTyp,3):" newline list recnum //PO&Set(JobTyp,allegro)&
Im Ausgabetemplate allegro.htm wird nun die Verarbeitung der Ankreuzungen geregelt, es gibt viele Formularfelder namens reccheck, zunächst folgt ein verstecktes Feld mit den sortierten Satznummern aus den (nach Blätteroperationen möglichen) vorigen Seiten in Reccheckpre, dann die einzelnen Checkboxes mit korrekten Vor-Ankreuzungen, dann ein weiteres verstecktes Feld mit den sortierten Satznummern aus Reccheckpost. Die aktuellen Ankreuzungen sind (ebenfalls korrekt sortiert) in Reccheckthis:
<!– evtl. zusätzliche Ankreuzungen –>
PO&IniVar(Extracheck,extracheck)&
<!– Aufteilen entsprechend Reihenfolge aus Recnums –>
PO&SplitChecknums(Reccheck,reccheck,Extracheck,Recnums)&
…
<form action="PO!Pop!" method="POST">
<!– Gesamtmenge der Sätze aufbewahren –>
<input type="hidden" name="recnums" value="PO!Recnums!">
PO?IF(Reccheckelsenum)?
PO!Reccheckelsenum! weiter(e) Titel bereits markiert
PO?ENDIF?
…
PO?IF(Reccheckpre)?
<input type="hidden" name="reccheck" value="PO!Reccheckpre!">
PO?ENDIF?
…
PO?LOOP?
…
<!– zu einzelnem Titel entscheiden, ob bereits angekreuzt –>
<input type="checkbox" name="reccheck" value="PO!L_Recno!"
PO?IF(CheckMe(Reccheckthis,L_Recno))?
checked="checked"
PO?ENDIF?
>
…
PO?ENDLOOP?
…
PO?IF(Reccheckpost)?
<input type="hidden" name="reccheck" value="PO!Reccheckpost!">
PO?ENDIF?
…
</form>
…
Falls sich aus Bereich eine (vierstellige) Jahreszahl als
„Startjahr“ identifizieren läßt, wird diese mit vorangesetztem
Präfixtext sowie Operator (
Korrespondiert zu (cf.). Nützlich, falls Jahreszahlenbereiche in einem Feld einzugeben sind, aber zwei Restriktionen ergeben sollen.
Beispiel (in einem Job):
…
PO&IniVar(Restriktion)&// Leere Variable 'Restriktion'
PO&IniVar(Jres,jres)&// Jres aus Aufruf-Feld belegen
PO&Assign(Tmp, StartRes(' and PYR', Jres))&
// Tmp ist jetzt leer oder von der Form
// ' and PYR>=JJJJ'
PO&Append(Restriktion, Tmp)&
PO&Assign(Tmp, EndeRes(' and PYR', Jres))&
// Tmp ist jetzt leer oder von der Form
// ' and PYR<=JJJJ'
PO&Append(Restriktion, Tmp)&
// Restriktion enthaelt jetzt null bis zwei Restriktionen
…
Falls gesetzt, wird der komplette QueryString
(Everything (cf.)) als Kommentar im Job für Avanti
übertragen, so daß es in der Logdatei landet.
Dabei werden die in @NoStat ( (cf.)) aufgeführten Felder
jedoch nicht mitprotokolliert.
Beschreibung siehe (cf.).
id=…/…
übertragen.
Falls $Debug ( (cf.)) gesetzt, werden
diagnostische Meldungen entsprechend den in Wantdebug
angegebenen Kategorien ausgegeben.
Eine Beschreibung der definierten Konfigurationsklassen findet sich im Abschnitt (cf.) über Debugmöglichkeiten.