Funktionsbeschreibungen

Funktion „get_gresult()“

Geschätzte Lektüre: 16 Minuten
array get_gresult(numeric $gtabid, numeric $utyp, array $filter, array $gsr, array $verkn, array $onlyfield=null, numeric $single=null, array $extension=null, numeric $pointer=null, bool $lmb_query=null, numeric $detailmode=null)

Funktion für die Tabellenabfrage (./limbas_src/gtab/gtab.lib).

Zusammenfassung der Parameter:

  • Spezifikation der Ziel-Tabelle mit $gtabid.
  • Anpassen der Ergebnisanzahl, anzeigen von versionierten/archivierten Datensätzen, Sortierung des Ergebnisses mit $filter.
  • Filtern der Ergebnismenge mit $gsr.
  • Filtern auf verknüpfte Datensätze mit $verkn.
  • Auswahl der Ergebnis-Felder mit $onlyfield.
  • Abfragen eines einzelnen Datensatzes mit $single.
  • Erweiterung des SQL-Queries mit $extension.
  • Pagination bei Abfragen mit $pointer.
  • SQL Query in globaler Variable mit $lmb_query.
  • Detailgrad der Ausgabe mit $detailmode.

Parameter:

$gtabid

  • gültige Tabellen-ID: Die Abfrage wird auf die entsprechende Tabelle angewandt.
  • ungültige Tabellen-ID: Die Abfrage gibt eine Fehlermeldung zurück.

$utyp

Für $utyp sind folgende Werte gültig:

  • 1: Standard
  • 0: Einstellung für Spezialfälle, die hier nicht weiter erläutert werden.

$filter

  • null: Alle Datensätze, die den Kriterien der anderen Übergabeparametern entsprechen, sind im Rückgabewert enthalten
  • Gültige Einstellungen im $filter-Array wirken sich auf die interne Ergebnismenge der Datenbank oder die Datensätze im Rückgabewert aus:

Ausweitung der internen Ergebnismenge

$filter["nolimit"][$gtabid] = $nolimit;

Für $nolimit sind folgende Werte gültig:

  • 1: Die Anzahl der Datensätze in der internen Ergebnismenge der Datenbank ist unbegrenzt
  • 0: Die Anzahl der Datensätze in der internen Ergebnismenge der Datenbank ist durch den Wert der Umgebungsvariablen „resultspace“ begrenzt.

Pagination

$filter["anzahl"][$gtabid] = $anzahl;

Für $anzahl sind folgende Werte gültig:

  • ‚all‘: Alle Datensätze aus der internen Ergebnismenge der Datenbank werden im Rückgabewert berücksichtigt
  • Zahl größer 0: „$anzahl“ Einträge aus der internen Ergebnismenge der Datenbank werden im Rückgabewert berücksichtigt
  • default: Gibt es für diese Einstellung keine Angabe, so wird der Wert aus der Einstellung für die „max. Anzahl Treffer“ aus den Benutzerdaten des angemeldeten Benutzers verwendet
$filter["page"][$gtabid] = $page;

Für $page sind folgende Werte gültig:

  • Zahl kleiner gleich 1: Die Datensätze, die im Rückgabewert berücksichtigt werden, werden aus der internen Ergebnismenge der Datenbank ohne Offset ausgewählt.
  • Zahl größer 1: Die Datensätze, die im Rückgabewert berücksichtigt werden, werden aus der internen Ergebnismenge der Datenbank mit dem Offset „$page * $anzahl“ ausgewählt. Ist dieser Offset größer als die Anzahl der Datensätze der internen Ergebnismenge, so wird kein Offset verwendet.

Sortierung

$filter["order"][$gtabid][$ordernumber] = array($gtabid,$tabellenfeldId,$order);

Mit der aufsteigenden $ordernumber können Unter-Sortierungen angegeben werden. Dabei beginnt die $ordernumber normalerweise mit 0.
Für $order sind folgende Werte gültig:

  • ‚ASC‘: Die Sortierung der Datensätze in der internen Ergebnismenge der Datenbank erfolgt aufsteigend nach dem Inhalt des Tabellenfeldes mit der ID „$tabellenfeldId“
  • ‚DESC‘: Die Sortierung der Datensätze in der internen Ergebnismenge der Datenbank erfolgt absteigend nach dem Inhalt des Tabellenfeldes mit der ID „$tabellenfeldId“

Soll bei gleichen Inhalt nach weiteren Tabellenfeldern sortiert werden, können mehrere derartige Anweisungen gesetzt werden.

Filtern auf Datensatz-Eigenschaften

archiviert

$filter["unhide"][$gtabid] = $unhide;

Für $unhide sind folgende Werte gültig:

  • -1: Datensätze werden nicht gefiltert
  • 0: Es werden nur nicht-archivierte Datensätze ausgegeben
  • Andere Werte: Nur archivierte Datensätze werden im Rückgabewert berücksichtigt

versioniert

$filter["viewversion"][$gtabid] = $viewversion;

Für $viewversion sind folgende Werte gültig:

  • 0: Einstellung ohne Auswirkung
  • Zahl ungleich 0: Bei versionierten Datensätze werden auch die älteren Datensätze im Rückgabewert berücksichtigt

gesperrt

$filter["locked"][$gtabid] = $locked;

Für $locked sind folgende Werte gültig:

  • 0: Einstellung ohne Auswirkung
  • Zahl ungleich 0: Nur gesperrte Datensätze werden im Rückgabewert berücksichtigt

mit Wiedervorlage

$filter["gfrist"][$gtabid] = $gfrist;

Für $gfrist sind folgende Werte gültig:

  • 0: Einstellung ohne Auswirkung
  • Zahl ungleich 0: Nur die Datensätze, deren Wiedervorlage-Zeit abgelaufen ist, werden im Rückgabewert berücksichtigt

Verknüpfte Datensatz-IDs

$filter["relationval"][$gtabid] = 1;

Der Filter „relationval“ bewirkt, dass man anstatt der Anzahl der verküpften Datensätze die IDs der verknüpften Datensätze als Array erhält.

Filtern nach Gültigkeit

$filter["validity"][$gtabid] = $date;

Über den Filter „validity“ kann eine mit dem Parameter „validity“ gekennzeichnete Tabelle nach einem Datum gefiltert und somit nur die in diesem Zeitraum gültigen Datensätze angezeigt werden. NULL Werte in den entsprechenden von/bis Feldern werden als gültig betrachtet. Folgende Werte sind zulässig:

  • [datum] (es werden gültige Datensätze des angegebenen Datums zurück gegeben)
  • ‚all‘ (es werden gültige und nicht gültige Datensätze zurück gegeben)
  • ‚allfrom‘ (es werden gültige und zukünftige Datensätze zurück gegeben)
  • ‚allto‘ (es werden gültige und vergangene Datensätze zurück gegeben)
  • ‚allactive‘ (es werden alle Datensätze der letzten Version eines Versionsstranges zurück gegeben)

Sonstiges

Weitere Einstellungen im $filter-Array sind für Spezialfälle, die hier nicht weiter erläutert werden.

$filter["report"][$gtabid] = $report;
$filter["hidelocked"][$gtabid] = $hidelocked;
$filter["nosverkn"][$gtabid] = $nosverkn;
$filter["alter"][$gtabid] = $alter;
$filter["groupheader"][$gtabid]
$filter["groupheaderKey"][$gtabid]
$filter["tabulatorKey"]
$filter["gwidth"][$gtabid]
$filter["ext_RelationFields"]
$filter["formrelation"]
$filter["getlongval"]
$filter["report"]

$gsr

  • null: alle Datensätze, die den Kriterien der anderen Übergabeparametern entsprechen, sind im Rückgabewert enthalten
  • Durch gültige Einstellungen im $gsr-Array lassen sich Filter definieren, die bewirken, dass im Rückgabewert nur Datensätze mit bestimmten Inhalten berücksichtigt werden.

Ein gsr-Filter wird definiert durch eine Operation und einen Operanden. Bei der Auswertung wird die Operation mit dem Inhalt des entsprechenden Datenfeldes und dem Operanden ausgeführt. Als Ergebnis ergibt sich ein true/false-Wert. Mehrere gsr-Filter können per and/or kombiniert werden. Beim Endergebnis „false“ wird der Datensatz nicht im Rückgabewert berücksichtigt.

Mit folgenden Konstrukten können Operation und Operand des Filters gesetzt werden (die Variable „$laufendeNr“ kann dabei frei gewählt werden, muss aber bei den zwei bzw. drei Zuweisungen für einen Filter jeweils identisch sein):

Texte

Text-Operation (ohne Berücksichtigung von Groß-/Kleinschreibung)

$gsr[$gtabid][$tabellenfeldId][$laufendeNr] = $operand;
$gsr[$gtabid][$tabellenfeldId]['txt'][$laufendeNr] = $operationID;

Für die $operationID sind folgende Werte verfügbar:

  • 1: Überprüfung, ob der im Operanden angegebene Text im Inhalt des Datenfeldes enthalten ist ( %$% ) (default)
  • 2: Überprüfung, ob der im Operanden angegebene Text identisch mit dem Inhalt des Datenfeldes ist ( == )
  • 3: Überprüfung, ob der Inhalt des Datenfeldes mit dem im Operanden angegebene Text anfängt ( $% )
  • 4: Überprüfung, ob der Inhalt des Datenfeldes ähnlich wie der angegebene Text klingt ( metaphone )
  • 5: Überprüfung, ob der Inhalt des Datenfeldes mit dem im Operanden angegebenen Text endet ( %$ )
  • 7: Überprüfung, ob der Inhalt des Datenfeldes leer ist
  • 8: Überprüfung, ob der Inhalt des Datenfeldes nicht leer ist

Bei Verwendung der Postgres Indizierung:

  • 9: Überprüfung, ob alle Wörter in dem Text vorkommen
  • 10: Überprüfung, ob eines der Wörter in dem Text vorkommt
  • 11: Überprüfung, ob der Satz in dem Text vorkommt

Berücksichtigung von Groß-/ Kleinschreibung

$gsr[$gtabid][$tabellenfeldId]['cs'][$laufendeNr] = 1;

Text-Operation für Texte aus Dateien bzw. Datenfelder des Typs long unter Verwendung der Index-Suche

$gsr[$gtabid][$tabellenfeldId][$laufendeNr] = $operand;
$gsr[$gtabid][$tabellenfeldId]['string'][$laufendeNr] = $operationID;

Für die $operationID ist folgender Wert verfügbar:

  • 1: Überprüfung, ob der im Operanden angegebene Text im Inhalt des Datenfeldes bzw. der verwiesenen Datei enthalten ist unter Berücksichtigung von Groß-/Kleinschreibung (?). Diese Operation ist nur möglich bei Indizierung aller Worte in der Reihenfolge des Vorkommens (Umgebungsvariable „indize_level“ = 2).

Zahlen

Numerische Operation

$gsr[$gtabid][$tabellenfeldId][$laufendeNr] = $operand;
$gsr[$gtabid][$tabellenfeldId]['num'][$laufendeNr] = $operationID;

Für die $operationID sind folgende Werte verfügbar:

  • 1: Überprüfung, ob der im Operanden angegebene Wert gleich dem Inhalt des Datenfeldes ist ( = )
  • 2: Überprüfung, ob der im Operanden angegebene Wert größer als der Inhalt des Datenfeldes ist ( > )
  • 3: Überprüfung, ob der im Operanden angegebene Wert kleiner als der Inhalt des Datenfeldes ist ( < )
  • 4: Überprüfung, ob der im Operanden angegebene Wert kleiner oder gleich dem Inhalt des Datenfeldes ist ( <= )
  • 5: Überprüfung, ob der im Operanden angegebene Wert größer oder gleich dem Inhalt des Datenfeldes ist ( >= )
  • 6: Überprüfung, ob der im Operanden angegebene Wert ungleich dem Inhalt des Datenfeldes ist ( != )
  • 7: Überprüfung, ob das Datenfeld leer ist (NULL)
  • 8: Überprüfung, ob das Datenfeld nicht leer ist (NOT NULL)

Datum

$gsr[$gtabid][$tabellenfeldId][$laufendeNr] = $operand;
$gsr[$gtabid][$tabellenfeldId]['num'][$laufendeNr] = $operationID;

Für den $operand werden folgende Formate unterstützt (Bezeichnung: Beispiele)

  • Kalenderwoche: KW3, KW 4 2020, cw 14
  • Nur Jahr: 1976, 2020
  • Jahr mit Monat: 12.1976, 4.2020
  • Volles Datum (mit oder ohne Zeit) (Formate unterstützt von strtotime())

Für die $operationID werden folgende Formate unterstütz: Siehe Zahlen.

Negation

  • Negation einer Abfrage
$gsr[$gtabid][$tabellenfeldId][$laufendeNr] = $operand;
...
$gsr[$gtabid][$tabellenfeldId]['neg'][$laufendeNr] = 1;

Mehrere Filter (and/or)

Bei mehreren Filtern pro Tabellenfeld ist ab dem zweiten Filter die folgende Zuweisung zu ergänzen:

$gsr[$gtabid][$tabellenfeldId]['andor'][$laufendeNr] = $operationID;

Für die $operationID sind folgende Werte verfügbar:

  • 1: Der Filter wird mit den bisherigen AND-verknüpft (default)
  • 2: Der Filter wird mit den bisherigen OR-verknüpft

Bei mehreren Verknüpfungen mit wechselnder Verknüpfungsart ist der Vorrang von der verwendeten Datenbank abhängig. Die Umgebungsvariable „searchcount“ definiert, wie viele Filter pro Tabellenfeld maximal berücksichtigt werden.

Bei Filter für mehrere Tabellenfelder definiert die folgende Zuweisung, wie diese verknüpft werden (ein Wechsel zwischen AND/OR ist hier nicht möglich):

$gsr[$gtabid]['andor'] = $operationID;

Für die $operationID sind folgende Werte verfügbar:

  • 1: Die Ergebnisse der Filter werden AND-verknüpft (default)
  • 2: Die Ergebnisse der Filter werden OR-verknüpft

$verkn

  • null oder 0: Alle Datensätze, die den Kriterien der anderen Übergabeparametern entsprechen, sind im Rückgabewert enthalten.
  • Array, das sinnvollerweise mit der Funktion init_relation() generiert wird: Im Rückgabewert werden nur Datensätze berücksichtigt, die mit dem durch die Übergabeparameter von init_relation() spezifizierten Tabellenfeld verknüpft sind.
  • ungültiger Wert: Der Rückgabewert enthält keine Datensätze.

$onlyfield

  • null: Die Datensätze im Rückgabewert beinhalten alle Tabellenfelder.
  • $onlyfield[$gtabid] = array($tabellenfeldId1, $tabellenfeldId2, …): Die Datensätze im Rückgabewert beinhalten nur die gelisteten Tabellenfelder
  • wird ein array() mit für diese Abfrage ungültigen Daten übergeben, enthält der Rückgabewert keine Datensätze
  • wird nur der String „ID“ übergeben, enthält der Rückgabewert nur systemspezifische Angaben sowie die ID der Datensätze

$single

Dieser Parameter ist für die Verwendung bei Tabellen (nicht bei Abfragen) vorgesehen. Er sollte nur gesetzt werden, wenn $pointer=null/0 ist. Ist dieser Wert gesetzt wird der $verkn Parameter ignoriert.

  • null oder 0: Alle Datensätze, die den Kriterien der anderen Übergabeparametern entsprechen, sind im Rückgabewert enthalten.
  • gültige Datensatz-ID: Der Rückgabewert enthält nur den Datensatz mit der übergebenen Datensatz-ID, vorausgesetzt er entspricht den Kriterien der anderen Übergabeparameter.
  • ungültige Datensatz-ID: Der Rückgabewert enthält keine Datensätze.

$extension

Über diesen Parameter kann das generierte SQL Statement individuell erweitert werden.

Folgende Erweiterungen sind möglich:

  • select
    • erweitert die „SELECT“ Komponente des SQL Statement. Es können eigene Felder oder Aliase hinzugefügt werden.
      $extension[’select‘][0] = „TABELLENNAME.FELDNAME„;
  • from
    • erweitert die „FROM“ Komponente des SQL Statement. Es können eigene Tabellen oder Aliase hinzugefügt werden.
      $extension[‚from‘][0] = „TABELLENNAME„;
  • where
    • erweitert die „WHERE“ Komponente des SQL Statement.
      $extension[‚where‘][0] = „Bedingung„;
  • order
    • ersetzt die interne Sortierung.
      $extension[‚order‘][0] = „FELDNAME„;
  • ojoin
    • erweitert die „OUTER JOIN“ Komponente des SQL Statements. Es können eigene LEFT/RIGHT (OUTER) JOINS hinzugefügt werden.
      $extension[‚ojoin‘][LINKER TABELLENNAME][RECHTER TABELLENNAME][0] = „Bedingung„; // LEFT (OUTER) JOIN
      $extension[‚ojoin‘][LINKER TABELLENNAME][RECHTER TABELLENNAME][‚LEFT‘][0] = „Bedingung„; // LEFT (OUTER) JOIN
      $extension[‚ojoin‘][LINKER TABELLENNAME][RECHTER TABELLENNAME][‚RIGHT‘][0] = „Bedingung„; // RIGHT (OUTER) JOIN
  • distinct
    • erweitert die Abfage zum ignorieren doppelter Ergebnisse.
      $extension[„distinct“] = „DISTINCT“;


$pointer

Dieser Parameter ist für die Verwendung bei Abfragen vorgesehen. Er sollte nur gesetzt werden, wenn $single=null/0 ist.

  • null oder 0: Alle Datensätze, die den Kriterien der anderen Übergabeparametern entsprechen, sind im Rückgabewert enthalten.
  • gültige relative Position eines Datensatzes in der internen Ergebnismenge der Datenbank: Der Rückgabewert enthält nur den Datensatz, welcher sich in der internen Ergebnismenge der Datenbank an der übergebenen Position befindet, vorausgesetzt er entspricht den Kriterien der anderen Übergabeparameter.
  • ungültige relative Position eines Datensatzes in der internen Ergebnismenge der Datenbank: Der Rückgabewert enthält keine Datensätze.

$lmb_query

Ist dieser Parameter „true“ wird in der globalen Valiable $GLOBALS[‚lmb_query‘] das zugrundeliegende SQL Query gespeichert mit dem die Abfrage ausgeführt worden ist.

$detailmode

Dieser Parameter definiert den Detailgrad mit dem die Ausgabe formatiert werden soll. Wird er nicht gesetzt so entspricht die Ausgabe bis auf einige Ausnahmen der Datenbank. Ansonsten wird die Ausgabe je nach Typ unterschiedlich aufbereitet. Unter anderem werden Verknüpfungen oder Multiselectfelder aufgelöst oder Datums und Numerische Felder formatiert. Nutzung des Detailmodus kann Auswirkungen auf die Performance der Abfrage haben.

  • typ 0/false = default
  • typ 3 = return for html export (with htmlentities, returns only simple text)
  • typ 4 = return for soap export with arrays (with htmlentities, returns many details as associated array)
  • typ 5 = return for raw export with arrays (returns multiple results as simple array)
  • typ 6 = return for rest api

Rückgabewert:

Im folgenden sind einige der möglichen Werte des zurückgegebenen Arrays erläutert. Welche Werte tatsächlich gesetzt sind, hängt von den Eingabeparametern ab.

  • [$gtabid][res_count]
    • Anzahl der durch die Abfrage ermittelten Datensätze in der Ergebnismenge der Datenbank
  • [$gtabid][need_time]
    • benötigte Zeit für die SQL-Abfrage der Datenbank
  • [$gtabid][max_count]
    • Anzahl der durch die Abfrage ermittelten Datensätze in der Ergebnismenge der Datenbank
  • [$gtabid][res_next]
    • Gibt die Position des ersten in diesem Rückgabewert enthaltenen Datensatzes in der internen Ergebnismenge der Datenbank an
  • [$gtabid][res_viewcount]
  • [$gtabid][LOCK][SELF][]
  • [$gtabid][LOCK][TIME][]
  • [$gtabid][LOCK][USER][]
  • für alle ($anzahl) ermittelten Datensätze:
  • für alle Tabellenfelder der Tabelle:
  • [$gtabid][$tabellenfeldid][0..($anzahl-1)“]
    • Tabelleninhalt
  • [$gtabid][id][0..($anzahl-1)“]
    • von LIMBAS vergebene eindeutige ID des Datensatzes (siehe auch Auto-ID)
  • [$gtabid][ERSTDATUM][0..($anzahl-1)“]
    • Datum der Erstellung des Datensatzes (siehe auch Post-Date)
  • [$gtabid][EDITDATUM][0..($anzahl-1)“]
    • Datum der der letzten Änderung des Datensatzes (siehe auch Edit-Date)
  • [$gtabid][EDITUSER][0..($anzahl-1)“]
    • Name des Benutzers, der den Datensatz als letztes verändert hat (siehe auch Edit-User)
  • [$gtabid][ERSTUSER][0..($anzahl-1)“]
    • Name des Benutzers, der den Datensatz erstellt hat (siehe auch Post-User)
  • [$gtabid][DEL][0..($anzahl-1)“]
    • 0: Der Datensatz ist nicht archiviert →1: Der Datensatz ist archiviert.
  • [$gtabid][INUSE_TIME][0..($anzahl-1)“]
  • [$gtabid][INUSE_USER][0..($anzahl-1)“]
  • [$gtabid][IS_OWN_USE][0..($anzahl-1)“]
  • [$gtabid][VID][0..($anzahl-1)“]
  • [$gtabid][VPID][0..($anzahl-1)“]
  • [$gtabid][VACT][0..($anzahl-1)“]
  • [$gtabid][VDESC][0..($anzahl-1)“]
  • [$gtabid][IS_OWN_USER][0..($anzahl-1)“]
Share this Doc

Funktion „get_gresult()“

Or copy link

CONTENTS