Signatur
Beschreibung
yaz_scan_result() liest die Ergebnisse eines zuvor mit yaz_scan() angestoßenen Scan-Vorgangs aus. Ein Z39.50-Scan ermöglicht das Durchsuchen eines Index-Bereichs eines Datenbankservers, um z. B. alphabetisch benachbarte Terme zu einem Suchbegriff zu ermitteln.
Die Funktion gibt ein zweidimensionales Array zurück, dessen Elemente jeweils einen gefundenen Term sowie dessen Häufigkeit (Anzahl der Treffer im Index) enthalten. Außerdem können über den optionalen Parameter $result zusätzliche Metadaten zum Scan-Ergebnis, wie die Gesamtzahl der Terme, abgerufen werden.
Typischer Einsatz ist die Implementierung einer Autovervollständigungs- oder Browse-Funktion für bibliografische Datenbanksysteme, die das Z39.50-Protokoll unterstützen, etwa in Bibliothekskatalogen oder Archivsystemen.
Wichtig: Die Funktion gehört zur PECL-Erweiterung yaz und setzt eine aktive, synchronisierte Verbindung voraus. Sie sollte erst nach dem Aufruf von yaz_wait() verwendet werden, da die Ergebnisse erst dann vollständig vorliegen.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $id Pflicht | resource | Eine YAZ-Verbindungsressource, die zuvor mit yaz_connect() erzeugt wurde. |
|
| $result | array | null | Optionaler Ausgabe-Parameter (per Referenz). Nach dem Aufruf enthält dieses Array zusätzliche Metadaten zum Scan-Ergebnis, z. B. den Schlüssel number (Anzahl der zurückgelieferten Terme) und stepSize. |
Rückgabewert
term (der gefundene Index-Term als String) und occurrences (Anzahl der Datensätze, in denen der Term vorkommt). Im Fehlerfall oder bei leerem Ergebnis wird ein leeres Array zurückgegeben.Beispiele
Scan nach alphabetisch benachbarten Termen
<?php
// Verbindung zu einem Z39.50-Server herstellen
$id = yaz_connect('z3950.example.org/MYDB');
// Scan im Titel-Index ab dem Begriff "Goethe" starten
yaz_scan($id, 'rpn', '@attr 1=4 "Goethe"');
// Auf Ergebnis warten
yaz_wait();
// Fehler prüfen
$error = yaz_error($id);
if ($error) {
echo "Fehler: " . $error;
} else {
$result = [];
$terms = yaz_scan_result($id, $result);
echo "Gefundene Terme: " . $result['number'] . "\n";
foreach ($terms as $entry) {
echo $entry['term'] . ' (' . $entry['occurrences'] . ' Treffer)' . "\n";
}
}
?>Metadaten des Scan-Ergebnisses auswerten
<?php
$id = yaz_connect('z3950.example.org/MYDB');
yaz_scan($id, 'rpn', '@attr 1=1003 "Schiller"');
yaz_wait();
$meta = [];
$terms = yaz_scan_result($id, $meta);
if (!empty($meta)) {
echo "Schrittgröße: " . ($meta['stepSize'] ?? 'n/a') . "\n";
echo "Anzahl Terme: " . ($meta['number'] ?? 0) . "\n";
}
foreach ($terms as $t) {
printf("%-40s %5d\n", $t['term'], $t['occurrences']);
}
?>// Wichtig · Fallstricke
Veraltete Erweiterung: Die yaz-Erweiterung (PECL) wird aktiv kaum noch weiterentwickelt und ist in modernen PHP-Umgebungen selten verfügbar. Prüfe, ob sie mit extension_loaded('yaz') vorhanden ist.
Die Funktion liefert nur dann sinnvolle Ergebnisse, wenn zuvor yaz_wait() erfolgreich abgeschlossen wurde. Ein Aufruf ohne vorheriges Warten kann zu leeren oder inkonsistenten Daten führen.
Die Verfügbarkeit und Struktur der Metadaten im $result-Parameter hängt vom jeweiligen Z39.50-Server ab und ist nicht standardisiert.