3 Referenzteil

    1. Funktionen, Routinen und Variable
      1. Variable und Strukturen
      2. Funktionen
      3. Routinen
    2. Kontrollstrukturen
      1. Prototypen
      2. IF-ELSIF-ELSE-ENDIF
      3. LOOP-ENDLOOP
      4. STRUC-ENDSTRUC
      5. WHILE-ENDWHILE
    3. Ablauf
    4. alphabetische Liste der reservierten Namen
      1. AddResult (Routine)
      2. AHtm (Funktion)
      3. Append (Routine)
      4. Assign (Routine)
      5. AvantiErrHook (Hook)
      6. AvantiErrTrans (Konfigurationsvariable)
      7. AvantiHost (Konfigurationsvariable)
      8. AvantiPort (Konfigurationsvariable)
      9. CheckMe (Funktion)
      10. CheckPattern (Funktion)
      11. Collect (Routine)
      12. CollectQuery (Funktion)
      13. ContentType (Variable)
      14. DateForm (Konfigurationsvariable)
      15. Db (Variable)
      16. DbSubmitted (Variable)
      17. DbTime (Variable)
      18. Debug (Konfigurationsvariable)
      19. Declare (Routine)
      20. Defaults (Struktur)
      21. Dec (Hilfsfunktion)
      22. EndeRes (Hilfsunktion)
      23. ENV (Funktion)
      24. Everything (Funktion)
      25. Fetchit (Funktion)
      26. Future (Funktion)
      27. GetBrowser (Funktion)
      28. GetRecnums (Routine)
      29. Htm (Funktion)
      30. Inc (Hilfsfunktion)
      31. IniVar (Routine)
      32. INP (Funktion)
      33. Int (Funktion)
      34. Iso (Funktion)
      35. JobSubtyp (Variable)
      36. JobTemplExt (Variable)
      37. JobTyp (Variable)
      38. NoStat (Konfiguration)
      39. L_(Shortcut)
      40. Lin (Funktion)
      41. LineFlow (Konfiguration)
      42. LineTyp (Variable)
      43. LinkEscape (Hook)
      44. LinkIni (Hilfsroutine)
      45. Localize (Routine)
      46. MaskenSpecial (Struktur)
      47. Message (Routine)
      48. Modified (Variable)
      49. P_(Shortcut)
      50. OutTemplExt (Variable)
      51. Paginate (Routine)
      52. Passwd (Konfigurationsvariable)
      53. PathInfo (Konstante)
      54. Poke (Routine)
      55. Pop (Konstante)
      56. PopPath (Konstante)
      57. Powered (Konstante)
      58. PrepareQuery (Routine)
      59. PrintVariablesShort (Funktion)
      60. Query (Struktur)
      61. RealDb (Variable)
      62. Recnums (Variable)
      63. RedoJob (Variable)
      64. ResultHook (Hook)
      65. ReuseSocket (Konfigurationsvariable)
      66. ReverseRegister (Konfiguration)
      67. S_(Shortcut)
      68. SanifyRegister (Routine)
      69. Set (Routine)
      70. SocketTimeout (Konfigurationsvariable)
      71. SplitChecknums (Routine)
      72. StartRes (Hilfsunktion)
      73. Stat (Konfigurationsvariable)
      74. Stl (Konfigurationsvariable)
      75. STLmap (Hook)
      76. Timestamp (Variable)
      77. User (Konfigurationsvariable)
      78. Version (Konstante)
      79. WantDebug (Konfigurationsvariable)
Nachdem in den vorigen Kapiteln eine Übersicht über populo gegeben wurde folgen nun Präzisierungen und Syntaxregeln für die populo-Steuersprache.

verwendete Notationen:

3.1 Funktionen, Routinen und Variable

Zur Kenntlichmachung von populo-Sprachelementen dienen die Zeichenfolgen

PO!…!
für Variablen und Funktionen,
PO&…&
für Routinen (die im Gegensatz zu Funktionen keinen Rückgabewert haben) und
PO?…?
für Kontrollstrukturen.
Zusätzlich gibt es für .job-Dateien noch die Zeichenfolge
PO:…:
für Variablen und Befehle, die von populo erst nach Erhalt des Ergebnisses von Avanti ausgewertet werden sollen.

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 dem ersten Begrenzungszeichen keine Leerzeichen (oder sonstige Zeichen) erlaubt, Leerzeichen zwischen den verwendeten Begrenzungszeichen und dem jeweiligen Inhalt werden allerdings ignoriert. Die Konstruktionen PO!…! und PO:…: dürfen das jeweilige Begrenzungszeichen ('!' bzw. ':') nicht in ihrem Inneren enthalten, bei Zeilen mit den Konstruktionen PO&…& oder PO?…? darf das jeweilige Begrenzungszeichen ('&' bzw. '?') hingegen im Rest der Zeile nicht mehr auftreten. (2)

3.1.1 Variable und Strukturen

PO!Variable!

Variable enthalten stets Zeichenketten, die jedoch auch als Wahrheitswerte ('' und '0' sind „falsch“, alle anderen Werte wahr) und Zahlwerte benutzt werden können.

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 '_' an den Variablennamen, der dabei nur aus einem Großbuchstaben bestehen darf, angehängt. Der komplette Variablenname inklusive '_' und Index verhält sich dann wie der Name einer einfachen Variable, nur daß keine Zuweisungen daran erfolgen dürfen. Indizierte Variablen kommen in populo hauptsächlich im Zusammenhang mit Strukturen vor, etwa beim Zugriff via der Routine 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 '[…]' gehören hier zur Syntax von Perl, sie kennzeichnen in Perl anonyme Arrays (3).

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>

3.1.2 Funktionen

PO!Funktion(Argument [,Argument …])!
PO! …Funktion(Argument) …!
PO&Routine( …Funktion(Argument) …)&
POKontrollstruktur( …Funktion(Argument) …)?

Funktionen liefern ein Resultat, welches bei Auswertungen anstelle des Funktionsaufrufs eingesetzt wird.

3.1.3 Routinen

PO&Routine(Argument [,Argument …])&
write …"PO:Routine(Argument [,Argument …]):" newline

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 ':' benutzt, so wird die Auswertung der Routine auf den Zeitpunkt des Zurücklesens des Resultats von Avanti verlegt, somit können von Avanti berechnete Zeichenketten verarbeitet werden.

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

3.2 Kontrollstrukturen

PO?Kontrollstruktur[(Argument [,Argument …])]?

PO?ENDKontrollstruktur[(beliebiger Text])?

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 '<', '<=', '==', '!=', '>=', '>', ' lt ', ' le ', ' eq ', ' ne ', ' ge ' und ' gt ', sowie ' = ' und ' ! ', ausserdem die logischen Verkettungsoperatoren ' &&' und ' || '.

3.2.1 Prototypen

3.2.2 IF-ELSIF-ELSE-ENDIF

PO?IF(<Bedingung1>)?
Anweisungen1
[PO?ELSIF(<Bedingung2>)?
Anweisungen2]
[…]
[PO?ELSE[Kommentar]?
Anweisungen_else]
PO?ENDIF[Kommentar]?
Prototyp: #e# für 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.

3.2.3 LOOP-ENDLOOP

PO?LOOP[(<Bedingung>)
?

PO?ENDLOOP[Kommentar]? ]

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.

3.2.4 STRUC-ENDSTRUC

PO?STRUC(Struktur, Indexsystem [, [<Auswahl>][, Shortcut]])?
Zeilen
PO?ENDSTRUC[Kommentar]?
Prototyp: #bb[eb#

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.

3.2.5 WHILE-ENDWHILE

PO?WHILE(Bedingung)?
Zeilen
PO?ENDWHILE[Kommentar]?
Prototyp: #[b#

Eine allgemeine Schleifenkonstruktion mit Bedingungsprüfung.

Solange Bedingung erfüllt ist, werden die Zeilen wiederholt.

3.3 Ablauf

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

&Aufrufpfad
am Anfang und
@ DB=Datenbank ID=User/Password
AVANTI:EOJ
am 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 '//' bei .job-Dateien und eingeschlossen in '<!–…–>' bei .htm-Dateien).

Eine Anfrage wird nun wie folgt bearbeitet:

  1. Die Eingabe wird interpretiert, insbesondere das Feld db wird ausgewertet und in die Variable Db überführt.

  2. Zu Db wird die Konfigurationsdatei Db.pl geladen.

  3. JobTyp und JobSubTyp werden (unter Rückgriff auf ein eventuelles Default) aus den HTTP-Feldern t_… bestimmt.

  4. unter Benutzung der Pfadliste aus $pathpraefix wird die zugehörige Templatedatei JobTyp.pl geöffnet.

  5. Die Templatedatei wird zeilenweise interpretiert und der Auftrag für Avanti generiert. Besteht dieser nur aus Kommentarzeilen (sinnvoll beim Aufbau von Formularen oder der Anzeige von Hilfsseiten), wird er nicht abgeschickt, ansonsten an Avanti übermittelt.

  6. Das Resultat des Auftrags wird zeilenweise zurückgelesen und dabei entweder PO:…:-Konstruktionen aufgelöst oder entsprechend den deklarierten LineTypen und den im Perl-Hash %LineFlow benannten Routinen vorverarbeitet.

  7. ist die Variable RedoJob gesetzt worden, so wird bei (cf.). fortgefahren.

  8. Die Verbindung zu Avanti wird beendet.

  9. Nicht gecachte Kurztitelzeilen werden direkt geladen, falls erlaubt.

  10. Das Resultat wird zwischenverarbeitet, um ggfls. Kurztitelzeilen in Registerauszüge einzusetzen oder Links im Ergebnis (LI:-Notation) aufzubereiten.

  11. Der HTTP-Header für die Ausgabe wird gesendet.

  12. Anhand des aktuellen JobTyp und unter Benutzung der Pfadliste aus $pathpraefix wird die Templatedatei JobTyp.htm für die Ausgabe geöffnet.

  13. Die Templatedatei wird zeilenweise interpretiert und ausgegeben. Die vorverarbeiten Zeilen des Resultats von Avanti werden dabei durch die LOOP-Konstruktionen aufgebraucht.

  14. Eventuell angefallene Debug-Informationen werden ausgegeben (4).

3.4 alphabetische Liste der reservierten Namen

3.4.1 AddResult (Routine)

PO&AddResult(<LineTyp>, <Inhalt>)&
Prototyp: #ee#

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 recnum
bzw.
find #PO!P_Recno!
write "PO:Set(LineTyp,13):" newline
list internal
und
//PO&AddResult(13, P_Recno)&

3.4.2 AHtm (Funktion)

PO!HtmA(<Argument>)!
Prototyp: #e#

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.).

3.4.3 Append (Routine)

PO&Append(Variable [,<Wert> [,…] ])&
Prototyp: #ve+#

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 '' initialisiert.

3.4.4 Assign (Routine)

PO&Assign(Variable, <Wert>)&
Prototyp: #v[e+#

Weist Variable das Ergebnis der Auswertung von Wert durch POeval zu.

3.4.5 AvantiErrHook (Hook)

Aus dem Resultat identifizierte Avanti-Fehlermeldungen werden an diese Routine übergeben, sofern sie definiert ist.

Beschreibung siehe (cf.).

3.4.6 AvantiErrTrans (Konfigurationsvariable)

%AvantiErrTrans = (
'130' => 'kein Ergebnis bei', …
)

Für die in der Variablen aufgeführten Errorcodes von Avanti wird der Text bis zum ersten Doppelpunkt durch den angegebenen Text ersetzt.

3.4.7 AvantiHost (Konfigurationsvariable)

$AvantiHost = '127.0.0.1';
$AvantiHost = 'avanti.biblio.etc.tu-bs.de';

IP-Nummer oder DNS-Name des zu befragenden Avanti-Servers.

3.4.8 AvantiPort (Konfigurationsvariable)

$AvantiPort = 4949;

Portnummer des zu befragenden Avanti-Servers.

3.4.9 CheckMe (Funktion)

PO!CheckMe(<Nummernvorrat>, <Testvorrat>)!
Prototyp: #ee#

Ist (eine der Satznummern aus) Testvorrat in Nummernvorrat enthalten?

Liefert den Rückgabewert '1' (wahr), wenn mindestens eine der Satznummern aus Testvorrat auch in Nummernvorrat vorkommt, ansonsten '0' (falsch).

Einsatz typischerweise in den Bedingungs-Argumenten von Kontrollstrukturen.

3.4.10 CheckPattern (Funktion)

PO!CheckPattern(<Zeichenfolge>, Teststring)!
Prototyp: #ee#

Ist Teststring in Zeichenfolge enthalten?

Im Prinzip obsolet, da IF-Konstruktionen Zeichenkettenvergleiche mittels regulärer Ausdrücke erlauben.

Liefert den Rückgabewert '1' (wahr), wenn Teststring im ersten Argument Zeichenfolge vorkommt.

Einsatz typischerweise in den Bedingungs-Argumenten von Kontrollstrukturen.

3.4.11 Collect (Routine)

PO&Collect(Struktur, feldmuster, Label)&
Prototyp: #bbb#

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 'text_1' bis 'text_5' für die Textfelder und 'pull_1' bis 'pull_5' für die korrespondierenden Pulldowns. Den Nummern 1 bis 5 entspreche die Deklaration

@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?

3.4.12 CollectQuery (Funktion)

find PO!CollectQuery(<Logik>, <Trunkierungszeichen>)!
Prototyp: #ee#

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.

3.4.13 ContentType (Variable)

//PO&Set(ContentType,text/x-sgml)&
Vorbelegung für HTTP-Header.

Vor der Ausgabe wird durch PrintHeader der HTTP-Content-Type angegeben. Belegen von ContentType gibt statt des Defaults 'text/html':

Content-type: ContentType
Leerzeile

3.4.14 DateForm (Konfigurationsvariable)

sprintf($DateForm, $mday, $mon, $year+1900, $hour, $min);
printf(3)-Template für das Datumsformat in Modified ( (cf.)) und DbTime ( (cf.)).

3.4.15 Db (Variable)

PO!Db!
Die Variable Db dient zur Identifikation der Datenbank und wird automatisch von populo aus dem Namen des Konfigurationsskripts oder dem HTTP-Feld db bestimmt.

3.4.16 DbSubmitted (Variable)

PO!DbSubmitted!
Die Variable DbSubmitted dient zur Identifikation der Datenbank und wird automatisch von populo aus dem HTTP-Feld db oder aus Db ( (cf.)) bestimmt.

3.4.17 DbTime (Variable)

PO!DbTime!
Datum der letzten Änderung der Konfigurationsdatei für die aktuelle Datenbank Db-Datei.

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.pl
auf den der Datenbank setzen. In den .htm-Templates können Sie dann mit PO!DbTime! stets das „Datum der Datenbank“ einblenden.

3.4.18 Debug (Konfigurationsvariable)

$Debug = 1;

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.

3.4.19 Declare (Routine)

PO&Declare(<Variable> [,<Variable> [,…] ])&
Prototyp: #v+#

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).

3.4.20 Defaults (Struktur)

%Defaults = (
JobTyp => 'maske',
'index' => 'PER', … );
Diese Struktur ist in der Konfigurationsdatei definiert und definiert Vorgaben für den Fall, daß HTTP-Felder nicht besetzt sind.

3.4.21 Dec (Hilfsfunktion)

PO!Dec(<Argument>)!
Prototyp: #e#

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 '<=' und '>=' bei der Formulierung von Restriktionen.

3.4.22 EndeRes (Hilfsunktion)

PO!EndeRes(Präfixtext,Bereich))!
Prototyp: #ee#

Falls sich aus Bereich eine (vierstellige) Jahreszahl als „Endejahr“ identifizieren läßt, wird diese mit vorangesetztem Präfixtext sowie Operator ('=', '<=', '<') zurückgegeben, falls erforderlich mit führenden Nullen.

Korrespondiert zu StartRes ( (cf.)). Nützlich, falls Jahreszahlenbereiche in einem Feld einzugeben sind, aber zwei Restriktionen ergeben sollen.

Beispiel bei (cf.).

3.4.23 ENV (Funktion)

PO!ENV(Environmentvariable)!
Prototyp: #b#

Zugriff auf Environment

Gibt den Inhalt der Environmentvariablen Environmentvariable zurück, falls diese belegt ist, sonst ''.

3.4.24 Everything (Funktion)

PO!Everything(<feld> [,<feld> [,…] ])!
Prototyp: #[b+#

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.)).

3.4.25 Fetchit (Funktion)

find #PO!Fetchit(<Force>)!
Prototyp: #e#

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.

3.4.26 Future (Funktion)

PO!Future(<Zeitoffset>)!
Prototyp: #b#

<Zeitoffset> ist dabei eine Folge von positiven oder negativen ganzen Zahlen mit angehängtem ''s'', ''m'', ''h'', ''d'' oder ''w'' (wobei auch Großbuchstaben erlaubt sind).

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)!">

3.4.27 GetBrowser (Funktion)

PO!GetBrowser()!
Prototyp: ##

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').

3.4.28 GetRecnums (Routine)

PO&GetRecnums(Variable, [<feld>, [<Extra>]])&
Prototyp: #v[be#

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ß).

3.4.29 Htm (Funktion)

PO!Htm(<Argument>)!
Prototyp: #e#

wandelt das Argument von ANSI nach HTML (7-bittig) um.

Vgl. AHtm ( (cf.)) für ASCII-Werte.

3.4.30 Inc (Hilfsfunktion)

PO!Inc(<Argument>)!
Prototyp: #e#

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 '<=' und '>=' bei der Formulierung von Restriktionen.

3.4.31 IniVar (Routine)

PO&IniVar(Variable)&
PO&IniVar(Variable, feld)&
PO&IniVar(Variable, [feld], Struktur)&
Prototyp: #v[bb#

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):

  1. Wert des HTTP-Feldes feld

  2. den #Default#-Wert der Struktur Struktur

  3. den Vorgabewert für feld aus dem in der datenbankspezifischen Datei Db.pl definiertem Hash %Defaults

  4. den Leerstring ''

3.4.32 INP (Funktion)

PO!INP(HTTP-Feld)!
Prototyp: #b#

Zugriff auf Eingabe

Gibt den Inhalt des Eingabefelds HTTP-Feld zurück, falls diese belegt ist, sonst das Default aus der Konfigurationsdatei, sonst ''.

3.4.33 Int (Funktion)

PO!Int(<Argument>)!
Prototyp: #e#

wandelt das Argument in eine ganze Zahl um

Insbesondere werden führende Nullen entfernt.

3.4.34 Iso (Funktion)

PO!Iso(<Argument>)!
Prototyp: #e#

wandelt das Argument von Ostwest-Windows nach ISO 8859-1 um.

Vgl. (cf.) für gleichzeitiges Konvertieren nach HTML.

3.4.35 JobSubtyp (Variable)

PO!JobSubTyp!
siehe PO!JobTyp!

3.4.36 JobTemplExt (Variable)

PO&Set(JobTemplExt, .<String>)&
Extension der Job-Templates, Default ist .job.

3.4.37 JobTyp (Variable)

PO!JobTyp!
PO!JobSubtyp!

Die Variable JobTyp bezeichnet die auszuführende Aktion, und korrespondiert mit .job und .htm-Dateien, JobSubtyp bietet eine Möglichkeit, zusätzliche Information weiterzugeben.

Der Wert von JobTyp wird aus den HTTP-Feldern bestimmt, die mit 't_' beginnen:

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 '.x' und '.y' werden von populo automatisch entfernt, dürfen umgekehrt aber auch nicht Bestandteil von Jobtypen sein.

Folgende reservierte JobTypen dienen zum Abfangen von Fehlerzuständen:

noans
Von Avanti wurde kein (vollständiges) Resultat übermittelt.
noconn
Es konnte nicht mit Avanti verbunden werden.
nojob
Es wurde keine .job-Datei zum spezifizierten JobTyp gefunden.
notyet
(Nicht mehr seit v1.20) Es konnte nicht mit Avanti verbunden werden, der Start des Servers wird aber von populo initiiert, die Anfrage wird nach einigen Sekunden automatisch wiederholt.

Alle diese JobTypen erfordern nur ein Ausgabetemplate (.htm-Datei), kein Jobtemplate JobTyp.job.

3.4.38 NoStat (Konfiguration)

@NoStat = qw(<HTTP-Feld> …);

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.

3.4.39 L_(Shortcut)

PO!L_0!
PO!L_Recno!
Unter diesem Shortcut sind die Elemente der Ergebniszeilen während der Ausführung einer LOOP-Schleife zugänglich ( (cf.))..

3.4.40 Lin (Funktion)

PO!Lin(<Argument>)!
Prototyp: #e#

wandelt das Argument in URL-codierte Form um (Als Link).

3.4.41 LineFlow (Konfiguration)

%LineFlow = (
'1' => \&DifferentiateRegister, #qrix, qrix title+

);
Entsprechend der Werte der Variablen LineTyp ( (cf.)) werden die von Avanti gelieferten Zeilen durch die hier definierten Unterprogramme weiterverarbeitet.

Beispiele und Vorbelegung siehe (cf.).

3.4.42 LineTyp (Variable)

PO!LineTyp!
Die Variable 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

3.4.43 LinkEscape (Hook)

In den Parameterdateien vorbereitete interne Links innerhalb der Datenbank werden ausgearbeitet.

Beschreibung siehe (cf.).

3.4.44 LinkIni (Hilfsroutine)

PO&LinkIni(Variable [,feld [,…] ])&
Prototyp: #v[b+#

Initialisiert Variable als URL mit den Werten der angegebenen felder (enthält als Beginn den Programmnamen und ist schon korrekt escaped)

3.4.45 Localize (Routine)

PO&Localize(Struktur, Schlüssel [,Shortcut])&
Prototyp: #be[b#

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&uuml;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!

3.4.46 MaskenSpecial (Struktur)

%MaskenSpecial = ('PER' => 'Persify,Trunkify,SR',…);
Diese Struktur ermöglicht es, beim Zusammenbauen von Suchbefehlen via 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.).

3.4.47 Message (Routine)

PO&Message(<Wert> [,<Wert> [,…] ])&
Prototyp: #e+#

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.

3.4.48 Modified (Variable)

PO!Modified!
Datum der letzten Änderung der aktuellen .htm-Datei

siehe auch DbTime.

3.4.49 P_(Shortcut)

PO!P_0!
PO!P_Recno!
Dies ist das Default-Shortcut für die Resultate von Paginate ( (cf.)).

3.4.50 OutTemplExt (Variable)

PO&Set(OutTemplExt, .<String>)&
Extension der Ausgabe-Templates, Default ist .htm.

3.4.51 Paginate (Routine)

PO&Paginate(<Ausgangsseite>, <Seitengröße>, <Aktion>, Nummern [,Shortcut])&
Prototyp: #eeee[b#

Paginate unterteilt die durch ',' getrennten Nummern in Blöcke von jeweils Seitengröße, und initialisiert Variable für den Block, der sich aus Ausgangsseite durch Anwendung der Aktion (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 '_' bestehen.)

Nummern muß der Name der Variablen sein, die die durch ',' getrennte Liste der internen Nummern anzuzeigender Datensätze enthält (als Zeichenkette).

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:

first
erste Seite
previous
oder - vorige Seite (Dekrement)
next
oder + nächste Seite (Inkrement)
last
letzte Seite
<Zahl>
Seite wird explizit gesetzt.
Alle anderen Werte von Ausgangsseite führen zu keiner Modifikation des Ausschnitts.

Paginate bestimmt nach diesen Angaben:

ShortcutNo
Nummer der neuen Seite (Ausgangsseite modifiziert)
ShortcutRecno
die Liste der (maximal Seitengröße) auf dieser Seite befindlichen Elemente aus Nummern
ShortcutStartNo
fortlaufende Nummer des ersten Satzes auf dieser Seite (von 0 gezählt)
ShortcutEndNo
fortlaufende Nummer des letzten Satzes auf dieser Seite (von 0 gezählt)
ShortcutTot
Nummer der letzten Seite
ShortcutIsFirst
Ist die aktuelle Seite die erste?
ShortcutIsLast
Ist die aktuelle Seite die letzte?

3.4.52 Passwd (Konfigurationsvariable)

PO!Passwd!
Wird am Ende des Avanti-Jobs als zweiter Wert für id=…/… übertragen.

3.4.53 PathInfo (Konstante)

PO!PathInfo!
Inhalt des PATH_INFO-Environments, d.h. von in der URL an den Scriptnamen per '/' angehängter weiterer Informationen.

3.4.54 Poke (Routine)

PO&Poke(Struktur, <Schlüssel>, Label, <Wert>)&
Prototyp: #bebe#

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.)

3.4.55 Pop (Konstante)

PO!Pop!
Name der aktuellen Instanz von populo.

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>

3.4.56 PopPath (Konstante)

PO!PopPath!
Virtueller Pfad der aktuellen Instanz von populo.

3.4.57 Powered (Konstante)

PO!Powered!
Netter String Allegro Avanti Populo Version.

3.4.58 PrepareQuery (Routine)

PO&PrepareQuery(Struktur, Indexsystem, Label1, Label2)&
Prototyp: #bbbb# Bereitet die Suchanfragen für Avanti auf.

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.

3.4.59 PrintVariablesShort (Funktion)

PO!PrintVariablesShort(Perl-Hash)!
Prototyp: ##

Gibt alle Schlüssel / Wertepaare des angegebenen assoziativen Vektors in einer HTML-aufbereiteten Form zurück.

3.4.60 Query (Struktur)

write "PO:Poke(Query,…,Treffer,Int(" lastnum ")):" n
Diese Struktur wird von PrepareQuery initialisiert und von CollectQuery benutzt. Eigene Einträge (etwa in das Feld Treffer können mit Poke hinzugefügt werden.

3.4.61 RealDb (Variable)

PO!RealDb!
siehe PO!Db!

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.

3.4.62 Recnums (Variable)

PO!Recnums!
PO!Recnumsnum!

Recnums enthält die Satznummern nach dem Einlesen von Zeilen vom LineTyp 5, getrennt durch ','.

Recnumsnum enthält die Anzahl der Elemente von Recnums.

Eine Zuweisung an diese Variable ist nicht erlaubt.

3.4.63 RedoJob (Variable)

PO!RedoJob!
Steuert erneute Verarbeitung von Jobs bzw. Verarbeitung weiterer Jobs.

Während der Vorverarbeitung der Job-Datei oder beim Zurücklesen des Resulats kann RedoJob auf '1' gesetzt werden, die (nochmalige) Verarbeitung des dem aktuellen Wert von JobTyp entsprechenden .job-Templates wird so erzwungen.

3.4.64 ResultHook (Hook)

Die aktuelle Zeile (vom LineTyp '4') ist in $_ und kann vor der Ausgabe noch individuell modifiziert werden.

Beschreibung siehe (cf.).

3.4.65 ReuseSocket (Konfigurationsvariable)

$ReuseSocket = Zahl;
Falls auf 0 gesetzt, wird pro Verbindung nur ein Avanti-Job abgewickelt, ist Zahl negativ, wird die Verbindung theoretisch unendlich oft weitergenutzt, bei positiver Zahl wird sie Zahl oft wiederbenutzt.

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.

3.4.66 ReverseRegister (Konfiguration)

%ReverseRegister = ('1' => 'PER', 'PER:' => 'PER')
Diese Struktur ist in der Konfigurationsdatei definiert und definiert die Umsetzung von registerübergreifenden Verweisen und vorbereiteten Hyperlinks auf symbolische Registernamen von Avanti.

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.

3.4.67 S_(Shortcut)

PO!S_0!
PO!S_Key!
Dies ist das Default-Shortcut für die Lokalisierungen während der Verarbeitung von Schleifen über die STRUC-Konstruktion ( (cf.)).

3.4.68 SanifyRegister (Routine)

PO&SanifyRegister(RegisterStruktur, RegisterSchlüssel [, Suchstring]&
Prototyp: #bb[e#

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 'A''z' einzugrenzen, die Benutzung ist aber nicht zwingend.

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:

RegStart
Kleinster erlaubter Eintrag im Register
RegEnde
Größter erlaubter Eintrag im Register

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.

3.4.69 Set (Routine)

PO&Set(Variable [,Wert])&
Prototyp: #v[e#

Weist Variable den (konstanten) Wert zu, oder den Leerstring '', falls kein zweiter Parameter angegeben wurde.

3.4.70 SocketTimeout (Konfigurationsvariable)

$SocketTimeout = Zahl;
Anzahl der Sekunden, die populo auf (Teil-)Resultate von Avanti wartet bzw. die populo versucht, einen Job an Avanti abzusenden.

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.

3.4.71 SplitChecknums (Routine)

PO&SplitChecknums(Variable, [feld, [<Extra>, [<Sortnums>]]])&
Prototyp: #v[bee#

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>
…

3.4.72 StartRes (Hilfsunktion)

PO!StartRes(Präfixtext,Bereich))!
Prototyp: #ee#

Falls sich aus Bereich eine (vierstellige) Jahreszahl als „Startjahr“ identifizieren läßt, wird diese mit vorangesetztem Präfixtext sowie Operator ('=', '<=', '<') zurückgegeben, falls erforderlich mit führenden Nullen.

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
…

3.4.73 Stat (Konfigurationsvariable)

$Stat = 1;

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.

3.4.74 Stl (Konfigurationsvariable)

Länge der Kurztiteleinträge der aktuellen Allegro-Datenbank. Diese Wert ist von der datenbankspezifischen Konfigurationsdatei Db.pl zu setzen.

3.4.75 STLmap (Hook)

Die Felder der gelesenen Kurzliste werden (für das Durchsortieren in erweiterten Registern) gemäß der hier programmierten Vorschrift in Sortierform gebracht.

Beschreibung siehe (cf.).

3.4.76 Timestamp (Variable)

PO!Timestamp!
aktuelles Datum und Uhrzeit.

3.4.77 User (Konfigurationsvariable)

PO!User!
Wird am Ende des Avanti-Jobs als erster Wert für id=…/… übertragen.

3.4.78 Version (Konstante)

PO!Version!
aktuelle Versionsnummer von populo.

3.4.79 WantDebug (Konfigurationsvariable)

@WantDebug = qw(Loggingklasse …);

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.