Hier werden die Unterschiede zwischen zwei Versionen angezeigt.
engine:procedures:if_mi_searchbinaries_conds [11.01.2016 ] |
engine:procedures:if_mi_searchbinaries_conds [11.01.2016 ] (aktuell) |
||
---|---|---|---|
Zeile 1: | Zeile 1: | ||
+ | ===== if_mi_SearchBinaries_Conds ===== | ||
+ | |||
+ | Fügt Suchbedingungen in die Input-Schnittstelle der internen Prozedur zur Suche von Binaries anhand von Werten zu deren Eigenschaften ("BinaryProperties") ein. Die Ausführung der eigentlichen Suche ist dann anschließend mit [[dstoreproc>mi_SearchBinaries_Ad]] oder einer der konreteren Implementierung wie [[dstoreproc>im_SearchBinaries_Ad]] auszuführen.\\ | ||
+ | |||
+ | |||
+ | |||
+ | Eine Suchbedingung besteht aus : | ||
+ | * einer "BinaryCharacteristicID" | ||
+ | * einer "Bedingung" | ||
+ | und | ||
+ | * "Optionen" (o.a. "SearchOptions") | ||
+ | |||
+ | |||
+ | Grundsätzlich besteht eine "Bedingung" aus einem "Operator1" und der dazugehörigen "Condition1", sowie optional aus einem weiteren "Operator2" und der dazugehörigen "Condition2". Folgende Möglichkeiten für "Operator1" gibt es : | ||
+ | * "=" | ||
+ | * "!=" -> %%|%% Diese beiden Operatoren sind grundsätzlich identisch und bedeuten | ||
+ | * "<>" -> %%|%% entweder "ungleich" oder "NOT LIKE" (je nach den "SearchOptions") | ||
+ | * ">" | ||
+ | * "<" | ||
+ | * ">=" | ||
+ | * "<=" | ||
+ | * "IN" -> "Condition1" muß dann eine Liste von Eigenschaftswerten enthalten, die durch die in "ValueSeparator_IN_Operator" angegebene Zeichenkette getrennt sind | ||
+ | |||
+ | |||
+ | Wenn "Operator2" etwas enthält, dann muß es eines der folgenden Zeichen sein : | ||
+ | * "<" | ||
+ | * "<=" | ||
+ | Außerdem muß in einem solchen Fall "Operator1" dann etweder ">" oder ">=" enthalten !\\ | ||
+ | |||
+ | |||
+ | |||
+ | Zu den "SearchOptions". Es muß eine Summe folgender Optionen (derzeit gibt es nicht wirklich viele...) sein : | ||
+ | * "1" : Der "LIKE"-Operator soll angewandt werden. | ||
+ | ACHTUNG : Diese Option ist nur erlaubt, wenn der Such-Operator (-> "Operator1") "=" oder "!=" ist.\\ | ||
+ | |||
+ | |||
+ | |||
+ | Man kann nun mehrere Suchbedingungen aufeinmal einfügen, und zwar in dem die einzelnen "Bestandteile" ("BinaryCharacteristicID", die "Bedingung" sowie die "Optionen) jeweils als "Liste" von Elementen, die durch die in "Separator" angegebene Zeichenkette getrennt sind, übergeben werden.\\ In "BinaryCharacteristicIDList" werden die "BinaryCharacteristicID"s übergeben, in "Operator1List" die "Operator1"-Werte usw.\\ | ||
+ | |||
+ | Die Werte in den "Condition..." und "Operator..."-Listen sind "string"-Werte und haben daher eine maximale Länge : | ||
+ | * Bei den beiden "Operator...List"-Parametern sind es jeweils 2 Byte | ||
+ | * Bei "Condition1List" darf ein Element 2500 Bytes nicht überschreiten | ||
+ | * Bei "Condition2List" lautet das Limit 1000 Bytes | ||
+ | Falls ein Element diese Grenze überschreitet, würde das Einfügen in die Tabelle zwar trotzdem gelingen, aber es würden unbemerkt Zeichen (am Ende) abgeschnitten und somit verloren gehen ! Daher wird auf die genannten Beschränkungen hin geprüft und ggf. ein Fehler ("-500") zurückgegeben.\\ | ||
+ | |||
+ | |||
+ | |||
+ | Sämtliche "..List"-Parameter müssen logischerweise immer die gleiche Anzahl Elemente, sprich die gleiche Anzahl "Separator" enthalten !\\ | ||
+ | |||
+ | ACHTUNG : Ist in einem "...List"-Parameter "Separator" zweimal direkt hintereinander enthalten oder ist "Separator" ganz am Anfang oder Ende eines "...List"-Parameters, dann enthält diese Liste quasi ein "leeres Element". Sind die Werte nun "strings", ist nicht klar, ob dies als "NULL" oder %%''%% zu interpretieren ist !\\ Daher wurde folgende Konvention getroffen : Ein leeres Element wird immer als "NULL" interpretiert !\\ | ||
+ | |||
+ | Möchte man aber %%''%% angeben (z.B. für "Condition1"), so sind zwei Fälle zu unterscheiden :\\ 1.) Wird nur EINE Bedingung übergeben, d.h. enthalten die "...List"-Parameter jeweils nur ein Element, belegt man den entsprechenden Parameter einfach mit %%''%%. Möchte man "NULL" angeben, setzt man ihn auch auf "NULL".\\ 2.) Werden MEHRERE Bedingungen angegeben, ist an der entsprechenden Stelle (also zwischen zwei "Separator"en bzw. am Anfang oder am Ende) ' ' (das Leerzeichen, ascii-code "32") anzugeben.\\ | ||
+ | |||
+ | Beispiele (wir gehen in allen Beispielen von "¶" als "Separator" aus) :\\ 1. " Condition1List = 'test¶ ' würde bedeuten, daß bei der ZWEITEN Bedingung %%''%% in die Spalte "Condition1" eingetragen wird\\ 2. " Condition1List = 'test¶' würde bedeuten, daß bei der ZWEITEN Bedingung "Condition1" "NULL" bleibt\\ 3. " Condition1List = NULL bedeutet, daß in der (einzigen) Bedingung "Condition1" "NULL" bleibt\\ 4. " Condition1List = ' ' (zwei aufeinander folgende Leerzeichen) bedeutet, daß %%''%% in "Condition1" eingetragen wird\\ | ||
+ | |||
+ | Hinweis : Man beachte, daß %%''%% (der "leere string") und ' ' (ein Leerzeichen) und ' ' (zwei Leerzeichen) identisch sind, d.h. ein Vergleich mit "=" ergibt "true" !\\ | ||
+ | |||
+ | |||
+ | |||
+ | Wenn man eine neue Suche startet, sollten evtl. von einer vorherigen Suche vorhandene Suchebedingungen natürlich vorher entfernt werden. Dazu ist "Delete" mit "1" zu belegen. Können nicht alle Suchbedingungen (wg. der "varchar(16384)"-Begrenzung) eingefügt werden, ruft man diese Prozedur einfach erneut auf, dann aber logischerweise mit "Delete = 0" !\\ | ||
+ | |||
+ | |||
+ | |||
+ | Nun einige Beispiel-Aufrufe und deren Bedeutung/Folgen :\\ | ||
+ | |||
+ | 1.) exec if_mi_SearchBinaries_Conds '3', '=', '%[Tt]limo', null, null, '1', 1\\ | ||
+ | |||
+ | => Es wird mit "LIKE" in Werten der Eigenschaften mit der "BinaryCharacteristicID = 3" gesucht, und es kommen nur die Werte in Frage, die auf "Tlimo" oder "tlimo" ENDEN.\\ | ||
+ | |||
+ | 2.) exec if_mi_SearchBinaries_Conds '3¶2', '=¶>=', '%[Tt]limo¶5000', '¶<=', '¶5100', '1¶0', 1\\ | ||
+ | |||
+ | => Wie Beispiel 1.) nur zusätzlich mit einer zweiten Suchbedingung, die folgendes ausdrückt : Es sollen nur Werte in Betracht kommen, die zwischen "5000" und "5100" liegen.\\ | ||
+ | |||
+ | 3.) exec if_mi_SearchBinaries_Conds '3', '=', '%[Tt]limo', null, null, '1', 1\\ und\\ exec if_mi_SearchBinaries_Conds '2', '>=', '5000', '<=', '5100', '0', 0\\ | ||
+ | |||
+ | => Stellen die gleichen zwei Suchbedingungen dar, wie eben in Beispiel 2.). Nur werden sie durch zwei getrennte Aufrufe eingefügt. Daher ist beim zweiten Aufruf der letzte Parameter-Wert (für "Delete") auch "0" !\\ | ||
+ | |||
+ | 4.) exec if_mi_SearchBinaries_Conds '3¶4', '=¶=', '%[Tt]limo¶%unzufrieden%', null, null, '1¶1', 1\\ | ||
+ | |||
+ | => Gibt einen Fehler ("-500"), da in "Operator2List" und "Condition2List" nur ein Element übergeben wurde. Richtig wäre :\\ | ||
+ | |||
+ | 5.) exec if_mi_SearchBinaries_Conds '3¶4', '=¶=', '%[Tt]limo¶%unzufrieden%', '¶', '¶', '1¶1', 1\\ | ||
+ | |HTTP-Method|GET | | ||
+ | |HTTP-Auth|Optional | | ||
+ | |Alias|if_mi_SearchBinaries_Conditions | | ||
+ | |Tags|{{tag>[if Search Binaries Conditions]}}| | ||
+ | |Engine-Kategorie|miscellaneous | | ||
+ | |Engine-Typ|Daten-Änderung | | ||
+ | |Letzte Aktualisierung|7.0.2 (2013-08-29)| | ||
+ | |||
+ | ==== Parameter ==== | ||
+ | |||
+ | ^Name ((Pflichtparameter sind unterstrichen)) ^Standard-Wert ^Beschreibung ((siehe [[webservice:engine_parameterconventions|Parameter-Konventionen engine/<Prozedur-Name>]])) ^SQL-Datentyp((siehe [[:webservice:engine_datatypes|Datentypen im Bereich "engine"]])) ^ab Version ^ | ||
+ | |__BinaryCharacteristicIDList__| |Liste von IDs (durch <Separator> getrennt), die Merkmale (für Binaries) darstellen - die angegebenen Werte werden in der Spalte "BinaryCharacteristicID" gespeichert\\ |varchar(1000)|7.0.1| | ||
+ | |__Operator1List__| |Liste (durch <Separator> getrennt) der einzufügenden Vergleichsoperatoren für den ersten Teil der Bedingung - die angegebenen Werte werden in der Spalte "Operator1" gespeichert\\ |varchar(1000)|7.0.1| | ||
+ | |__Condition1List__| |Liste (durch <Separator> getrennt) der einzufügenden Vergleichswerte für den ersten Teil der Bedingung - die angegebenen Werte werden in der Spalte "Condition1" gespeichert\\ |varchar(16384)|7.0.1| | ||
+ | |__Operator2List__| |Liste (durch <Separator> getrennt) der einzufügenden Vergleichsoperatoren für den zweiten Teil der Bedingung - die angegebenen Werte werden in der Spalte "Operator2" gespeichert\\ |varchar(1000)|7.0.1| | ||
+ | |__Condition2List__| |Liste (durch <Separator> getrennt) der einzufügenden Vergleichswerte für den zweiten Teil der Bedingung - die angegebenen Werte werden in der Spalte "Condition2" gespeichert\\ |varchar(16384)|7.0.1| | ||
+ | |__SearchOptionList__| |Liste (durch <Separator> getrennt) von "Such-Optionen" (s. Beschreibung) - die angegebenen Werte werden in der Spalte "SearchOptions" gespeichert\\ |varchar(1000)|7.0.1| | ||
+ | |Delete|0 |Möchte man zuvor die Input-Schnittstelle leeren, setzt man "Delete" auf "1".\\ |bit|7.0.1| | ||
+ | |Separator|'¶' |Gibt an, durch welche Zeichen die Werte in den "Listen-"Parametern ("...List") getrennt sind\\ |varchar(4)|7.0.1| | ||
+ | ==== Rückgabe ==== | ||
+ | |||
+ | Die Prozedur hat keine Rückgaben. | ||
+ | ==== Output-Parameter ==== | ||
+ | |||
+ | |InputNestingLevel|Gibt an, zu welchem "NestingLevel" die Daten eingefügt wurden (ein DIREKTER Aufruf führt immer zum Wert "2"). Diese Info braucht man für einen anschließenden Aufruf von z.B. [[dstoreproc>mi_SearchBinaries_Ad]] (Parameter "InputNestLevel_Conds").| | ||
+ | ==== Mögliche Return-Codes ==== | ||
+ | |||
+ | ^Code ^Beschreibung ^Quelle ((direkt meint "von der Prozedur selber" und indirekt meint "von intern aufgerufenen Unterprozeduren")) ^ | ||
+ | |-500|Falsche Parameter|direkt und indirekt| | ||
+ | ==== XML-Schema ==== | ||
+ | |||
+ | Die Rückgabe erfolgt als XML-Dokument welches gegen das Schema [[http://resources.dstore.de/xsd/webservice_SmartGate/Response/EngineProcedure_v1_0.xsd|Response/EngineProcedure_v1_0.xsd]] validiert. | ||
+ | ==== Historie ==== | ||
+ | |||
+ | |7.0.2 |2013-08-29|1. Überprüfung auf maximalen Byte-Länge von "string"-Elementen fehlte => Auch Hinweis in der Doku\\ 2. Ab jetzt kann ein Element in "Condition1List" bis zu 2500 Bytes und in "Condition2List" bis zu 1000 Bytes lang\\ sein [vorher jeweils 255]\\ | | ||
+ | |7.0.1 |2013-08-07|Erstmalig in dieser Version erstellt\\ | | ||
+ | |||
+ | ==== Code-Snippets ==== | ||
+ | |||
+ | Es handelt sich um eine Methode zum Füllen von Schnittstellentabelle wie in [[:engine:procedures-background#input_-tabellen|Hintergrundinformationen zu Engine-Prozeduren]] erläutert. Die Methode kann ausschließlich per engine/execute in einem gemeinsamen Batch mit komplementären Prozeduren verwendet werden.== engine/execute == | ||
+ | XML zur Ausführung mit der Methode [[:webservice:engine:execute|engine/execute]], z.B. per | ||
+ | curl --header 'Content-Type: application/xml' -X POST 'http://<partner>-<kunde>.dstore.de/default/engine/execute' -d '<xml-daten>' | ||
+ | |||
+ | <code xml> | ||
+ | <?xml version="1.0" encoding="UTF-8"?> | ||
+ | <ListOfBatches> | ||
+ | <Batch No="0"> | ||
+ | <Procedure Name="if_mi_SearchBinaries_Conds"> | ||
+ | <Parameters/> | ||
+ | </Procedure> | ||
+ | </Batch> | ||
+ | </ListOfBatches></code> | ||