OpaccERP logo

F-Script

Grundlagen

Query basiert auf der Idee, dass SQL-Datenbank-Features besser genutzt werden können und der lesende Zugriff (R/O-Teil der Business-Logik) direkt in der Datenbank abgebildet wird.
Query bietet Ihnen folgende Nutzen:
  • Effizientes und flexibles filtern und sortieren
  • Join-Möglichkeiten (Auflösen von Relationen zwischen BOs)
  • Hohe Performance
Query ist darüber hinaus, die Basis für zukünftige Erweiterungen.
Wichtig
Wichtig
Beachten Sie, dass nicht die ganze Business-Logik verfügbar ist.

Biz-Views

Die verwendeten Schemas, Tabellen-Namen, etc. stellen keine öffentliche Schnittstelle dar und können von uns jederzeit geändert werden. Auch entsprechen die Tabellen in der Datenbank in vielen Fällen nicht den BOs. Deshalb ist der direkte Zugriff auf Stufe der SQL-Datenbank nicht erlaubt! Durch die Verwendung unserer Services (GetBo und Query) ist sichergestellt, dass die Daten konsistent und funktional korrekt ausgelesen werden.
Biz-View.jpg

Query-Service

Der Zugriff auf die Datenbank (und damit auf die Daten) erfolgt über den Query-Service.
Query-Service.jpg

Verfügbarkeit in F-Script

Innerhalb von F-Script stehen die Befehle XQRY und XQRS zur Verfügung. Diese sind viel schneller, als der Umweg über das Ausführen von Query als Service (BUS in F-Script). Arbeiten Sie deshalb in F-Scripts immer mit diesen Befehlen!

Verfügbarkeit via ServiceBus

Für alle ServiceBus-Clients steht Query als ganz normaler Service zur Verfügung.
Query kann also in BOF-Scripts, durch 3rd-Party Anwendungen, über WebService, über COM (AIC), sowie durch FrontOffice und MobileOffice genutzt werden.

Biz-Views - Typen

Die Biz-Views unterteilen sich in drei Typen:
  • BO-Views - Kapselung des entsprechenden (persistenten) BO
  • Konstanten-Views - 1:1 Entsprechung der jeweiligen Konstanten
  • Funktions-Views - Verschiedene Ausprägungen
Der Zugriff auf Biz-Views ist nur via Query möglich.

BO-Views - Abbildung eines BO

BO-Views bilden BOs (z.B. Addr) ab. Dabei entsprechen die BO-Attribute den View-Spalten.
Wichtig
Wichtig
Beachten Sie, dass in einem BO nicht immer alle Attribute über die BO-View verfügbar sind.

Konstanten-Views

Konstanten-Views bilden Konstanten (z.B. AddrType) ab. Dabei entspricht der Konstanten-Wert der View-Spalte.
Alle Konstanten und ihre Werte sind über die Konstanten-Views verfügbar.

Funktions-Views

Im Gegensatz zu den beiden anderen View-Typen, müssen beim Aufruf von Funktions-Views Argumente angegeben werden.
Funktions-Views existieren in unterschiedlichen Ausprägungen bzw. stellen unterschiedliche Funktionen zur Verfügung.
  • Nachbildung eines berechneten BO
    Beispiel: AddrText
  • Nachbildung von abgeleiteten (z.B. sprachabhängigen) BO-Attributen
    Beispiel: Salut_Name
  • Nachbildung eines spezifischen Service
    Beispiel: Addr_SearchByBarcode
  • Neue Funktionalität bzw. ausschliesslich via Query verfügbar
    Beispiel: Empl_AddrCircle

Meta-Modell

Der Zugriff auf alle Biz-View-Elemente erfolgt mittels GetInfoQuery... Abfragen.
  • Zugriff auf Biz-View: GetInfoQueryView
  • Zugriff auf Biz-View-Spalte: GetInfoQueryViewCol
  • Zugriff auf Biz-View-Argument: GetInfoQueryViewArg
  • Zugriff auf Biz-View-Relation: GetInfoQueryViewRel
Insbesondere kann via GetInfoQuery... Abfragen die Verfügbarkeit geprüft werden. (ViewItemStateCd)
Die View-Element-Status und deren Bedeutung:
CodeValue CodeId Info
NA
NotAvailable
Das Element ist nicht verfügbar und wird aller Voraussicht nach auch zukünftig nicht verfügbar sein.
NA_YET
NotAvailableYet
Das Element ist nicht verfügbar, wird aber voraussichtlich in Zukunft verfügbar sein.
AV_PUB
AvailablePublic
Das Element ist öffentlich verfügbar und kann in Query-Service-Aufrufen verwendet werden.
AV_PRIV
AvailablePrivate
Das Element ist nur für interne (Opacc eigene) Zwecke verfügbar. Es kann in Query-Service-Aufrufen nicht verwendet werden.

GetInfoQuery - View-Element-Informationen abrufen

Informationen bezüglich allen Biz-View-Elementen. (Elemente welche innerhalb einer Query-Abfrage benutzt werden können.)
In erster Linie ist dieser Service für den MLS-Text-Generator bestimmt. (Mit einer Abfrage können alle relevanten MLS-Text-Keys bestimmt werden.)

GetInfoQueryView - View-Informationen abrufen

Informationen über die Verfügbarkeit und den Typ von Biz-Views. (Views welche innerhalb eines Query-Aufrufs benutzt werden können.) Man beachte, dass Elemente mit dem Status 'AV_PRIV' oder 'NA' im Normalfall nicht zurückgegeben werden.

GetInfoQueryViewCol - View-Spalten-Informationen abrufen

Informationen bezüglich Biz-View-Spalten. (Spalten/Columns von Views, welche innerhalb einer Query-Abfrage benutzt werden können.) Man beachte, dass Elemente mit dem Status 'AV_PRIV' oder 'NA' im Normalfall nicht zurückgegeben werden.

GetInfoQueryViewArg - View-Argument-Informationen abrufen

Informationen bezüglich Biz-View-Argumenten. (Argumente von Funktions-Views, welche innerhalb einer Query-Abfrage benutzt werden können.) Man beachte, dass Elemente mit dem Status 'AV_PRIV' oder 'NA' im Normalfall nicht zurückgegeben werden.

GetInfoQueryViewRel

Informationen bezüglich Biz-View-Relationen. (Relationen von Views welche innerhalb einer Query-Abfrage benutzt werden können.) Man beachte, dass Elemente mit dem Status 'AV_PRIV' oder 'NA' im Normalfall nicht zurückgegeben werden.

ContextInfo

ContextInfo ist eine spezielle View, welche in beliebigen Query-Abfragen verwendet werden kann. Sie enthält folgende Attribute:
  • ClientNo
  • UserNo (angemeldeter Benutzer)
  • UserAddrNo (angemeldeter Benutzer)
  • UserGroupNo (angemeldeter Benutzer)
  • DataLangNo
  • UiLangNo
  • DataLangNoDefault
  • UiLangNoDefault
  • RoundToQuantity
  • RoundToWeight
  • RoundToPrice
  • OwnCostsAccess (Gibt Auskunft darüber, ob im jeweiligen Kontext der Zugriff auf Deckungsbeiträge etc. erlaubt ist.)
  • DataLangNoDefault (Sprachnummer - Default-Datensprache)
  • UiLangNoDefault (Sprachnummer - Default-Beschriftungssprache)
Die obigen Attribute können Sie bei beliebigen Query-Aufrufen als Columns hinzufügen.

Zusätzliche ID-Spalten

BoPid

Objekt-PID (Persistent ID) von BO-Views.
BoPid ist eine Spalte, welche in allen BO-Views enthalten ist. Die BoPid ist innerhalb einer BO-View eindeutig. Da sie von der Performance her besser ist als die BoId, sollte sie bei Query-Abfragen bevorzugt verwendet werden. Da die BoPid eindeutig ist, eignet sie sich insbesondere als (allenfalls ergänzendes) Sortier-Attribut bei Query-Abfragen mit Scrolling. (Siehe auch: Scrolling)

RowId

Row-ID von Funktions-Views.
RowId ist eine universelle Spalte, welche in Funktions-Views enthalten sein kann. Die RowId ist innerhalb einer Funktions-View eindeutig. Da die RowId eindeutig ist, eignet sie sich ebenfalls als (allenfalls ergänzendes) Sortier-Attribut bei Query-Abfragen mit Scrolling. (Siehe auch: Scrolling)

Zweck, Limitationen und Argumente

Query ist (Zweck):
  • Das Instrument für lesenden Zugriff auf Biz-Views
  • Eine Ergänzung zu GetBo und SelectBo
Limitationen von Query:
  • Der Kontext auf BOs und deren Attribute ist fixiert auf: "NoContext"
  • Es gibt keine 1:1 Unterstützung der Qualifier: @, @@, $, $$ und !, !!
Argumente von Query-Abfragen:
  • Query-Argumente sind nach folgendem Muster aufgebaut: Name=Value
    Beispiel: Filter=Addr.FullName like '*AG
  • Argumente und Filter sind case-sensitiv!
    Objekt-Identifier beginnen mit Grossbuchstaben, Funktionen/Operatoren beginnen mit Kleinbuchstaben.
  • Welche Argument-Namen unterstützt werden, kann der Referenz entnommen werden.

Unterschiede zwischen Query und GetBo

Argument-Reihenfolge

Query-Requests sind, im Gegensatz zu normalen Service-Requests, nicht fix aufgebaut (Struktur). Die Reihenfolge der Argumente ist daher nicht zwingend vorgegeben. Darüber hinaus können einige Argumente (z.B. Column) mehrmals vorkommen.
Wir empfehlen aufgrund der besseren Lesbarkeit, folgenden Aufbau:
  • Main=<BO>
  • MaxRows=<Anzahl>
  • Filter=<Filter-Expression>
  • Columns=<Spalten (n)>
  • Column=<Alias>,<Spalte>
  • Related=<Relation>
  • OrderBy=<Sortierung>
  • Distinct=<0/1> oder Distinct=<FALSE/TRUE>

Überschreiben von bestehenden Requests

Ein bestehender Query-Request kann, im Gegensatz zu normalen Service-Requests, nicht mit neuen Argumenten überschrieben werden.
Soll derselbe Query-Request zwei Mal hintereinander - mit unterschiedlichen Argumenten - ausgeführt werden, dann muss das Request-Objekt vor der zweiten Ausführung mit dem Befehl clear geleert werden.
«XQRY(<requestName>:clear)»

Abfragen aller Spalten mit "*" ist nicht möglich

Da Query-Abfragen mehr als eine Relation erlauben und auch Relationen über mehrere Ebenen möglich sind, müssen die gewünschten Rückgabe-Attribute explizit definiert werden.

Abfragen ohne Resultat (keine Rückgabe)

Wird eine Query-Abfrage ausgeführt, die aufgrund der gewählten Selektion (Filter, etc.) kein Resultat zurückliefert, führt dies zu einem Fehler.
Bei Query-Abfragen muss deshalb zwingend eine Validierung von mText (Error-Meldung) und/oder rows (Anzahl Resultat-Records) erfolgen.

Fehlermeldungen von Query-Abfragen

Die häufigsten bzw. wichtigsten Fehlermeldungen in der Übersicht:
Fehlermeldung Grund / Ursache 
DmlQuery_Execute: At least one 
Argument 'Column' expected
Ein zwingendes Argument wurde nicht angegeben.
Hier im Beispiel fehlt: Column.
 
DmlQuery_GetValueOfNamedColumn: 
There is no public column with 
name Addr.Number Parametername: 
columnName
Der tatsächliche Wert war 
Addr.Number.%%LogMsgEnd%%
Dieser Fehler kann zwei Ursachen haben:
  • Es wird eine Spalte abgefragt die nicht als Column definiert wurde.
  • Es werden Spalten abgefragt obwohl keine Rows zurückgegeben wurden. (Resultat = 0 Rows)
 
DmlQuery_Execute: 
Creating SQL string for 
'Addr.FirstNames' failed: 
Creating SQL string for Expression-Tree 
failed: 
Identifier 'Addr.FirstNames' 
is not known.
Dieser Fehler kann zwei Ursachen haben:
  • Das Attribut exisitiert nicht. (Tippfehler oder falsches Attribut.)
  • Das Attribut existiert nicht als View-Attribut. (Siehe GetInfoQueryViewCol)
Hier im Beispiel wurde Addr.FirstNames geschrieben anstatt Addr.FirstName